{ "openapi": "3.1.0", "info": { "title": "Octospark Agent API", "version": "0.1.0", "summary": "Public API surface for Octospark CLI, MCP, and SDK clients.", "description": "The Octospark Agent API is the public surface behind the Octospark CLI, MCP server, and generated SDKs: draft, schedule, and publish social posts, manage the media library, and read analytics and billing, all scoped to your organizations and teams.\n\n**Authentication.** Every request needs a bearer token (`Authorization: Bearer `). Agent clients obtain one via `octospark login` (device authorization) or an organization API key; see the Authentication page.\n\n**Pagination.** List endpoints return `{ data, total, nextCursor, prevCursor }`. `nextCursor`/`prevCursor` are opaque and null at the ends of the list; pass `nextCursor` back as the `cursor` query parameter to fetch the next page. `limit` caps page size (default 25, max 100).\n\n**Publishing.** `POST .../posts/{postId}/schedule` and `POST .../posts/{postId}/post-now` fan one post out to one or more connected accounts (`socialAccountIds`) and return a per-account result list plus an `outcome` summary (`none_failed`, `partially_failed`, `all_failed`). Send an `Idempotency-Key` header so timed-out retries replay the original result instead of double-publishing.\n\n**Costs.** Publishing to costed providers and live account analytics reads spend organization credits; check the credit balance endpoint before costed calls. Mutating and paid operations are confirmation-gated in the CLI/MCP clients, which preview costs before executing." }, "paths": { "/v1/organizations": { "get": { "tags": [ "Organizations" ], "operationId": "organizations.listOrganizations", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, "required": false, "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "Page size as a positive integer string; defaults to 25, capped at 100.", "default": "25", "examples": [ "25", "100" ] }, "required": false, "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt.", "examples": [ "createdAt" ] }, "required": false, "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt." }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc or desc; defaults to desc.", "default": "desc" }, "required": false, "description": "Sort direction: asc or desc; defaults to desc." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "billingEmail", "onboardingData", "stripeCustomerId", "stripeSubscriptionId", "stripePaymentMethodId", "stripeMeteredSubscriptionItemId", "creditsBalance", "reservedCredits", "autoRechargeEnabled", "autoRechargeThreshold", "autoRechargeAmount", "isSubscribed", "subscriptionStatus", "subscriptionPlan", "subscriptionStartedAt", "subscriptionEndsAt", "subscriptionCurrentPeriodEnd", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "billingEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "onboardingData": { "anyOf": [ { "type": "object", "required": [ "version", "status", "currentStep", "completedSteps" ], "properties": { "version": { "type": "number", "enum": [ 1 ] }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] }, "currentStep": { "type": "string", "enum": [ "organization_profile", "job_role", "workspace_setup", "goals", "mcp_cli_setup", "spend_cap", "completed" ] }, "completedSteps": { "type": "array", "items": { "type": "string", "enum": [ "organization_profile", "job_role", "workspace_setup", "goals", "mcp_cli_setup", "spend_cap", "completed" ] } }, "organizationProfile": { "type": "object", "required": [ "displayName" ], "properties": { "displayName": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 2, "maxLength": 64 }, "jobRole": { "type": "string", "enum": [ "developer_or_technical_founder", "founder_or_owner", "marketing_or_social", "agency_or_client_services", "operations_or_admin", "other" ] } }, "additionalProperties": false }, "workspaceProfile": { "type": "object", "required": [ "teamName", "website" ], "properties": { "teamName": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 2, "maxLength": 64 }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "goals": { "type": "object", "required": [ "primaryGoal", "teamSize" ], "properties": { "primaryGoal": { "type": "string", "enum": [ "vibe_marketing", "social_media_marketing", "automated_campaigns_for_clients" ] }, "teamSize": { "type": "string", "enum": [ "1-5", "6-20", "21-50", "51+" ] } }, "additionalProperties": false }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "stripeCustomerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stripeSubscriptionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stripePaymentMethodId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stripeMeteredSubscriptionItemId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "creditsBalance": { "type": "number" }, "reservedCredits": { "type": "number" }, "autoRechargeEnabled": { "type": "boolean" }, "autoRechargeThreshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "autoRechargeAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "isSubscribed": { "type": "boolean" }, "subscriptionStatus": { "type": "string", "enum": [ "active", "inactive", "trialing", "past_due", "canceled", "paused", "unpaid" ] }, "subscriptionPlan": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subscriptionStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subscriptionEndsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subscriptionCurrentPeriodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the organizations the caller belongs to. Organizations own billing, credits, and teams; use the returned organizationId for billing and usage endpoints. For a one-call overview of user, organizations, teams, and default ids, prefer GET /v1/agent/context.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.organizations.listOrganizations({\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.organizations.list_organizations()" }, { "lang": "CLI", "label": "CLI", "source": "octospark orgs list" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let url = format!(\"{}/v1/organizations\", base_url.trim_end_matches('/'));\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/organizations';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List organizations", "x-displayName": "List organizations" }, "post": { "tags": [ "Organizations" ], "operationId": "organizations.createOrganization", "parameters": [], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "billingEmail", "onboardingData", "stripeCustomerId", "stripeSubscriptionId", "stripePaymentMethodId", "stripeMeteredSubscriptionItemId", "creditsBalance", "reservedCredits", "autoRechargeEnabled", "autoRechargeThreshold", "autoRechargeAmount", "isSubscribed", "subscriptionStatus", "subscriptionPlan", "subscriptionStartedAt", "subscriptionEndsAt", "subscriptionCurrentPeriodEnd", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "billingEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "onboardingData": { "anyOf": [ { "type": "object", "required": [ "version", "status", "currentStep", "completedSteps" ], "properties": { "version": { "type": "number", "enum": [ 1 ] }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] }, "currentStep": { "type": "string", "enum": [ "organization_profile", "job_role", "workspace_setup", "goals", "mcp_cli_setup", "spend_cap", "completed" ] }, "completedSteps": { "type": "array", "items": { "type": "string", "enum": [ "organization_profile", "job_role", "workspace_setup", "goals", "mcp_cli_setup", "spend_cap", "completed" ] } }, "organizationProfile": { "type": "object", "required": [ "displayName" ], "properties": { "displayName": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 2, "maxLength": 64 }, "jobRole": { "type": "string", "enum": [ "developer_or_technical_founder", "founder_or_owner", "marketing_or_social", "agency_or_client_services", "operations_or_admin", "other" ] } }, "additionalProperties": false }, "workspaceProfile": { "type": "object", "required": [ "teamName", "website" ], "properties": { "teamName": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 2, "maxLength": 64 }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "goals": { "type": "object", "required": [ "primaryGoal", "teamSize" ], "properties": { "primaryGoal": { "type": "string", "enum": [ "vibe_marketing", "social_media_marketing", "automated_campaigns_for_clients" ] }, "teamSize": { "type": "string", "enum": [ "1-5", "6-20", "21-50", "51+" ] } }, "additionalProperties": false }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "stripeCustomerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stripeSubscriptionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stripePaymentMethodId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stripeMeteredSubscriptionItemId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "creditsBalance": { "type": "number" }, "reservedCredits": { "type": "number" }, "autoRechargeEnabled": { "type": "boolean" }, "autoRechargeThreshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "autoRechargeAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "isSubscribed": { "type": "boolean" }, "subscriptionStatus": { "type": "string", "enum": [ "active", "inactive", "trialing", "past_due", "canceled", "paused", "unpaid" ] }, "subscriptionPlan": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subscriptionStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subscriptionEndsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subscriptionCurrentPeriodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create a new organization with the caller as its admin. Organizations are the billing and credit boundary; create a team inside it next to start working with social accounts, assets, and posts. Organization deletion is not exposed on the public agent surface; it remains a web-app flow.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Organization display name, 2 to 64 characters.", "title": "maxLength(64)", "minLength": 2, "examples": [ "Acme Inc" ], "maxLength": 64 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.organizations.createOrganization({\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.organizations.create_organization(\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark organizations create-organization \\\n --request '{\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let url = format!(\"{}/v1/organizations\", base_url.trim_end_matches('/'));\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/organizations';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create organization", "x-displayName": "Create organization" } }, "/v1/organizations/{organizationId}": { "patch": { "tags": [ "Organizations" ], "operationId": "organizations.updateOrganization", "parameters": [ { "name": "organizationId", "in": "path", "schema": { "type": "string", "description": "Organization id (UUID). Discover ids via the list organizations endpoint or the agent context." }, "required": true, "description": "Organization id (UUID). Discover ids via the list organizations endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "billingEmail", "onboardingData", "stripeCustomerId", "stripeSubscriptionId", "stripePaymentMethodId", "stripeMeteredSubscriptionItemId", "creditsBalance", "reservedCredits", "autoRechargeEnabled", "autoRechargeThreshold", "autoRechargeAmount", "isSubscribed", "subscriptionStatus", "subscriptionPlan", "subscriptionStartedAt", "subscriptionEndsAt", "subscriptionCurrentPeriodEnd", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "billingEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "onboardingData": { "anyOf": [ { "type": "object", "required": [ "version", "status", "currentStep", "completedSteps" ], "properties": { "version": { "type": "number", "enum": [ 1 ] }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] }, "currentStep": { "type": "string", "enum": [ "organization_profile", "job_role", "workspace_setup", "goals", "mcp_cli_setup", "spend_cap", "completed" ] }, "completedSteps": { "type": "array", "items": { "type": "string", "enum": [ "organization_profile", "job_role", "workspace_setup", "goals", "mcp_cli_setup", "spend_cap", "completed" ] } }, "organizationProfile": { "type": "object", "required": [ "displayName" ], "properties": { "displayName": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 2, "maxLength": 64 }, "jobRole": { "type": "string", "enum": [ "developer_or_technical_founder", "founder_or_owner", "marketing_or_social", "agency_or_client_services", "operations_or_admin", "other" ] } }, "additionalProperties": false }, "workspaceProfile": { "type": "object", "required": [ "teamName", "website" ], "properties": { "teamName": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 2, "maxLength": 64 }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "goals": { "type": "object", "required": [ "primaryGoal", "teamSize" ], "properties": { "primaryGoal": { "type": "string", "enum": [ "vibe_marketing", "social_media_marketing", "automated_campaigns_for_clients" ] }, "teamSize": { "type": "string", "enum": [ "1-5", "6-20", "21-50", "51+" ] } }, "additionalProperties": false }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "stripeCustomerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stripeSubscriptionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stripePaymentMethodId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stripeMeteredSubscriptionItemId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "creditsBalance": { "type": "number" }, "reservedCredits": { "type": "number" }, "autoRechargeEnabled": { "type": "boolean" }, "autoRechargeThreshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "autoRechargeAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "isSubscribed": { "type": "boolean" }, "subscriptionStatus": { "type": "string", "enum": [ "active", "inactive", "trialing", "past_due", "canceled", "paused", "unpaid" ] }, "subscriptionPlan": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subscriptionStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subscriptionEndsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subscriptionCurrentPeriodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Update an organization's settings, such as its name. Only an organization admin or owner can do this. Membership changes go through the member endpoints, and organization deletion is not exposed on the public agent surface.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string", "description": "New organization display name, 2 to 64 characters.", "title": "maxLength(64)", "minLength": 2, "examples": [ "Acme Inc" ], "maxLength": 64 }, "onboardingData": { "anyOf": [ { "type": "object", "required": [ "version", "status", "currentStep", "completedSteps" ], "properties": { "version": { "type": "number", "enum": [ 1 ] }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] }, "currentStep": { "type": "string", "enum": [ "organization_profile", "job_role", "workspace_setup", "goals", "mcp_cli_setup", "spend_cap", "completed" ] }, "completedSteps": { "type": "array", "items": { "type": "string", "enum": [ "organization_profile", "job_role", "workspace_setup", "goals", "mcp_cli_setup", "spend_cap", "completed" ] } }, "organizationProfile": { "type": "object", "required": [ "displayName" ], "properties": { "displayName": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 2, "maxLength": 64 }, "jobRole": { "type": "string", "enum": [ "developer_or_technical_founder", "founder_or_owner", "marketing_or_social", "agency_or_client_services", "operations_or_admin", "other" ] } }, "additionalProperties": false }, "workspaceProfile": { "type": "object", "required": [ "teamName", "website" ], "properties": { "teamName": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 2, "maxLength": 64 }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "goals": { "type": "object", "required": [ "primaryGoal", "teamSize" ], "properties": { "primaryGoal": { "type": "string", "enum": [ "vibe_marketing", "social_media_marketing", "automated_campaigns_for_clients" ] }, "teamSize": { "type": "string", "enum": [ "1-5", "6-20", "21-50", "51+" ] } }, "additionalProperties": false }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ], "description": "Replacement onboarding wizard state for the organization; null clears it." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.organizations.updateOrganization({\n organizationId: process.env.OCTOSPARK_ORGANIZATION_ID ?? \"organizationId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.organizations.update_organization(\n organizationId=os.environ.get(\"OCTOSPARK_ORGANIZATION_ID\", \"organizationId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark organizations update-organization \\\n --request '{\"path\":{\"organizationId\":\"organizationId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let organization_id = env::var(\"OCTOSPARK_ORGANIZATION_ID\").unwrap_or_else(|_| \"organizationId\".to_string());\n let url = format!(\"{}/v1/organizations/{}\", base_url.trim_end_matches('/'), organization_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final organizationId = Platform.environment['OCTOSPARK_ORGANIZATION_ID'] ?? 'organizationId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/organizations/$organizationId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Update organization", "x-displayName": "Update organization" } }, "/v1/teams": { "get": { "tags": [ "Teams" ], "operationId": "teams.listTeams", "parameters": [ { "name": "organizationId", "in": "query", "schema": { "type": "string", "description": "UUID of the organization whose teams (workspaces) to list.", "examples": [ "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "UUID of the organization whose teams (workspaces) to list." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, "required": false, "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "Page size as a positive integer string; defaults to 25, capped at 100.", "default": "25", "examples": [ "25", "100" ] }, "required": false, "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt.", "examples": [ "createdAt" ] }, "required": false, "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt." }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc or desc; defaults to desc.", "default": "desc" }, "required": false, "description": "Sort direction: asc or desc; defaults to desc." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "organizationId", "name", "website", "linkTrackingDefault", "timezone", "postApprovalMode", "autoPostEnabled", "reviewBoardVisibleCategories", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "organizationId": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkTrackingDefault": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postApprovalMode": { "anyOf": [ { "type": "string", "enum": [ "off", "optional", "required" ] }, { "type": "null" } ] }, "autoPostEnabled": { "type": "boolean" }, "reviewBoardVisibleCategories": { "type": "array", "items": { "type": "string", "enum": [ "not_started", "active", "in_review", "completed", "closed" ] } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the teams the caller can access. Teams own social accounts, assets, folders, and posts, so most endpoints require a teamId from this list. For a one-call overview that also includes organizations and default ids, prefer GET /v1/agent/context.", "x-invariants": [ "INV-ORG-001" ], "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.teams.listTeams({\n query: {\n \"organizationId\": process.env.OCTOSPARK_ORGANIZATION_ID ?? \"organizationId\",\n },\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.teams.list_teams(\n query={\n \"organizationId\": os.environ.get(\"OCTOSPARK_ORGANIZATION_ID\", \"organizationId\"),\n }\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark teams list \\\n --request '{\"query\":{\"organizationId\":\"organizationId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let organization_id = env::var(\"OCTOSPARK_ORGANIZATION_ID\").unwrap_or_else(|_| \"organizationId\".to_string());\n let url = format!(\"{}/v1/teams\", base_url.trim_end_matches('/'));\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let query = [(\"organizationId\", organization_id.as_str())];\n request = request.query(&query);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final organizationId = Platform.environment['OCTOSPARK_ORGANIZATION_ID'] ?? 'organizationId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams';\n final uri = Uri.parse(url).replace(queryParameters: {\n 'organizationId': organizationId,\n });\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List teams", "x-displayName": "List teams" }, "post": { "tags": [ "Teams" ], "operationId": "teams.createTeam", "parameters": [], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "organizationId", "name", "website", "linkTrackingDefault", "timezone", "postApprovalMode", "autoPostEnabled", "reviewBoardVisibleCategories", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "organizationId": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkTrackingDefault": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postApprovalMode": { "anyOf": [ { "type": "string", "enum": [ "off", "optional", "required" ] }, { "type": "null" } ] }, "autoPostEnabled": { "type": "boolean" }, "reviewBoardVisibleCategories": { "type": "array", "items": { "type": "string", "enum": [ "not_started", "active", "in_review", "completed", "closed" ] } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create a team (workspace) inside an organization. Requires the create_teams permission. The new team starts empty: connect social accounts and upload assets before creating posts.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "organizationId", "name" ], "properties": { "organizationId": { "type": "string", "description": "UUID of the organization the team (workspace) belongs to.", "examples": [ "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "name": { "type": "string", "description": "Team (workspace) display name, 2 to 64 characters.", "title": "maxLength(64)", "minLength": 2, "examples": [ "Acme Marketing" ], "maxLength": 64 }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Brand website URL used for enrichment and display; null clears it.", "examples": [ "https://acme.com" ] } }, "additionalProperties": false } } }, "required": true }, "x-invariants": [ "INV-ORG-001" ], "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.teams.createTeam({\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.teams.create_team(\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark teams create-team \\\n --request '{\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let url = format!(\"{}/v1/teams\", base_url.trim_end_matches('/'));\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create team", "x-displayName": "Create team" } }, "/v1/teams/{teamId}": { "patch": { "tags": [ "Teams" ], "operationId": "teams.updateTeam", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "organizationId", "name", "website", "linkTrackingDefault", "timezone", "postApprovalMode", "autoPostEnabled", "reviewBoardVisibleCategories", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "organizationId": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkTrackingDefault": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postApprovalMode": { "anyOf": [ { "type": "string", "enum": [ "off", "optional", "required" ] }, { "type": "null" } ] }, "autoPostEnabled": { "type": "boolean" }, "reviewBoardVisibleCategories": { "type": "array", "items": { "type": "string", "enum": [ "not_started", "active", "in_review", "completed", "closed" ] } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Update a team's settings, such as its name. Membership changes go through the team member endpoints, not this one.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string", "description": "New team (workspace) display name, 2 to 64 characters.", "title": "maxLength(64)", "minLength": 2, "examples": [ "Acme Marketing" ], "maxLength": 64 }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Brand website URL used for enrichment and display; null clears it.", "examples": [ "https://acme.com" ] }, "linkTrackingDefault": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Default link-tracking toggle for new posts in this workspace; null resets to the plan default." }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone name (e.g. Europe/London) used to resolve this workspace's scheduling-slot wall-clock times to UTC instants; null clears it. Validated against the runtime's supported timezone list; an unsupported name is rejected with 400.", "examples": [ "Europe/London" ] }, "postApprovalMode": { "anyOf": [ { "type": "string", "enum": [ "off", "optional", "required" ] }, { "type": "null" } ], "description": "Client approval workflow mode: off hides review features and blocks new submit-for-review calls, optional (the default; null resets to it) enables the workflow as an advisory signal, required additionally blocks scheduling/publishing until the current content version is approved.", "examples": [ "required" ] }, "autoPostEnabled": { "type": "boolean", "description": "Whether eligible content workflow statuses can trigger automatic publishing." }, "reviewBoardVisibleCategories": { "type": "array", "items": { "type": "string", "enum": [ "not_started", "active", "in_review", "completed", "closed" ] }, "description": "Workflow categories the client review-board link surfaces (any subset of not_started, active, in_review, completed, closed). Default is [in_review, completed] - submitted + approved posts." } }, "additionalProperties": false } } }, "required": true }, "x-invariants": [ "INV-ORG-001" ], "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.teams.updateTeam({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.teams.update_team(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark teams update-team \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Update team", "x-displayName": "Update team" }, "delete": { "tags": [ "Teams" ], "operationId": "teams.removeTeam", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Delete a team. Requires the delete_teams permission. Cancels the team's scheduled work, including scheduled posts and pending publish actions, so check listPosts for upcoming publishes before calling. This is destructive and cannot be undone via the API.", "x-invariants": [ "INV-ORG-001" ], "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.teams.removeTeam({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.teams.remove_team(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark teams remove-team \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete team", "x-displayName": "Delete team" } }, "/v1/teams/{teamId}/social-accounts": { "get": { "tags": [ "Social accounts" ], "operationId": "social.listSocialAccounts", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "provider", "providerAccountId", "displayName", "profileHandle", "profileImageUrl", "accountSubType", "status", "scopes", "providerSettings", "capabilities", "connectedAt", "disconnectedAt", "createdAt", "updatedAt", "accountHealthIssue", "accountHealthMessage", "accountHealthSince" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "providerAccountId": { "type": "string" }, "displayName": { "type": "string" }, "profileHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "profileImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountSubType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "connected", "disabled", "refresh_needed", "disconnected" ], "description": "Connection state of a social account: connected (usable), disabled, refresh_needed (token expired, reconnect required), or disconnected.", "examples": [ "connected" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "providerSettings": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "capabilities": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "connectedAt": { "type": "string" }, "disconnectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "accountHealthIssue": { "anyOf": [ { "type": "string", "enum": [ "verification_required", "auth_failed", "rate_limited" ] }, { "type": "null" } ] }, "accountHealthMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountHealthSince": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List a team's connected social accounts with provider, handle, and connection status. Use the returned ids as the socialAccountIds array when calling schedulePost or postNow. Connecting new accounts happens via the OAuth flow, not this endpoint.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.listSocialAccounts({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.list_social_accounts(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark accounts list \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/social-accounts\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/social-accounts';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List social accounts", "x-displayName": "List social accounts" } }, "/v1/teams/{teamId}/social-accounts/{id}": { "get": { "tags": [ "Social accounts" ], "operationId": "social.getSocialAccount", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "id", "in": "path", "schema": { "type": "string", "description": "Connected social account id (UUID), as returned by the list social accounts endpoint." }, "required": true, "description": "Connected social account id (UUID), as returned by the list social accounts endpoint." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "provider", "providerAccountId", "displayName", "profileHandle", "profileImageUrl", "accountSubType", "status", "scopes", "providerSettings", "capabilities", "connectedAt", "disconnectedAt", "createdAt", "updatedAt", "accountHealthIssue", "accountHealthMessage", "accountHealthSince" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "providerAccountId": { "type": "string" }, "displayName": { "type": "string" }, "profileHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "profileImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountSubType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "connected", "disabled", "refresh_needed", "disconnected" ], "description": "Connection state of a social account: connected (usable), disabled, refresh_needed (token expired, reconnect required), or disconnected.", "examples": [ "connected" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "providerSettings": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "capabilities": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "connectedAt": { "type": "string" }, "disconnectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "accountHealthIssue": { "anyOf": [ { "type": "string", "enum": [ "verification_required", "auth_failed", "rate_limited" ] }, { "type": "null" } ] }, "accountHealthMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountHealthSince": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Fetch one connected social account by id, including provider, handle, and connection status. Use listSocialAccounts to discover account ids; use this when you need to verify a single account before publishing to it.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.getSocialAccount({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n id: process.env.OCTOSPARK_ID ?? \"id\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.get_social_account(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n id=os.environ.get(\"OCTOSPARK_ID\", \"id\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark accounts get \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"id\":\"id\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let id = env::var(\"OCTOSPARK_ID\").unwrap_or_else(|_| \"id\".to_string());\n let url = format!(\"{}/v1/teams/{}/social-accounts/{}\", base_url.trim_end_matches('/'), team_id, id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final id = Platform.environment['OCTOSPARK_ID'] ?? 'id';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/social-accounts/$id';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Get social account", "x-displayName": "Get social account" } }, "/v1/teams/{teamId}/posts": { "get": { "tags": [ "Posts" ], "operationId": "social.listPosts", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, "required": false, "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "Page size as a positive integer string; defaults to 25, capped at 100.", "default": "25", "examples": [ "25", "100" ] }, "required": false, "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt.", "examples": [ "createdAt" ] }, "required": false, "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt." }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc or desc; defaults to desc.", "default": "desc" }, "required": false, "description": "Sort direction: asc or desc; defaults to desc." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "idea", "proposed_render", "draft", "in_review", "approved", "rejected", "archived", "deleted" ], "description": "Filter to posts with this editorial status.", "examples": [ "draft" ] }, "required": false, "description": "Filter to posts with this editorial status." }, { "name": "workflowStatusId", "in": "query", "schema": { "type": "string", "description": "Filter to posts assigned to this workspace-defined content workflow status.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": false, "description": "Filter to posts assigned to this workspace-defined content workflow status." }, { "name": "provider", "in": "query", "schema": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Filter to posts whose latest scheduled post targets this provider.", "examples": [ "x" ] }, "required": false, "description": "Filter to posts whose latest scheduled post targets this provider." }, { "name": "scheduledFrom", "in": "query", "schema": { "type": "string", "description": "Only include posts scheduled at or after this ISO 8601 timestamp.", "examples": [ "2026-06-01T00:00:00Z" ] }, "required": false, "description": "Only include posts scheduled at or after this ISO 8601 timestamp." }, { "name": "scheduledTo", "in": "query", "schema": { "type": "string", "description": "Only include posts scheduled at or before this ISO 8601 timestamp.", "examples": [ "2026-06-30T23:59:59Z" ] }, "required": false, "description": "Only include posts scheduled at or before this ISO 8601 timestamp." }, { "name": "filter[q]", "in": "query", "schema": { "type": "string", "description": "Case-insensitive free-text search over the post title and latest payload text.", "examples": [ "product launch" ] }, "required": false, "description": "Case-insensitive free-text search over the post title and latest payload text." }, { "name": "filter[postType]", "in": "query", "schema": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel" ], "description": "Filter to posts of this content format.", "examples": [ "text_image" ] }, "required": false, "description": "Filter to posts of this content format." }, { "name": "filter[tab]", "in": "query", "schema": { "type": "string", "enum": [ "queue", "drafts", "sent" ], "description": "Queue/Drafts/Sent tab over the derived latest-scheduled-post status: queue = scheduled/publishing/failed, sent = published, drafts = never scheduled or a draft/cancelled latest scheduled post.", "examples": [ "queue" ] }, "required": false, "description": "Queue/Drafts/Sent tab over the derived latest-scheduled-post status: queue = scheduled/publishing/failed, sent = published, drafts = never scheduled or a draft/cancelled latest scheduled post." }, { "name": "filter[tagIds]", "in": "query", "schema": { "type": "string", "description": "CSV of user-tag UUIDs from the post_tags registry; matches posts assigned ANY of these tags. Unknown or foreign ids are ignored.", "examples": [ "4a1f4e93-0d8b-4a6c-9a44-1e8b1f2c3d4e,7b2c5f81-3e9d-4b7a-8c55-2f9c2a3b4c5d" ] }, "required": false, "description": "CSV of user-tag UUIDs from the post_tags registry; matches posts assigned ANY of these tags. Unknown or foreign ids are ignored." }, { "name": "filter[assignee]", "in": "query", "schema": { "type": "string", "enum": [ "me", "unassigned" ], "description": "Assignee quick filter: me = posts assigned to the calling user, unassigned = posts with no assignees.", "examples": [ "me" ] }, "required": false, "description": "Assignee quick filter: me = posts assigned to the calling user, unassigned = posts with no assignees." }, { "name": "filter[tags]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI tags; matches posts whose assets carry any of the listed tags (OR).", "examples": [ "launch,product" ] }, "required": false, "description": "Comma-separated AI tags; matches posts whose assets carry any of the listed tags (OR)." }, { "name": "filter[category]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI content categories; matches posts in any of the listed categories (OR).", "examples": [ "education" ] }, "required": false, "description": "Comma-separated AI content categories; matches posts in any of the listed categories (OR)." }, { "name": "filter[purpose]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI purposes; matches posts whose assets carry any of the listed purposes (OR).", "examples": [ "promotion" ] }, "required": false, "description": "Comma-separated AI purposes; matches posts whose assets carry any of the listed purposes (OR)." }, { "name": "filter[emotion]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI emotions; matches posts tagged with any of the listed emotions (OR).", "examples": [ "joy" ] }, "required": false, "description": "Comma-separated AI emotions; matches posts tagged with any of the listed emotions (OR)." }, { "name": "filter[mediaType]", "in": "query", "schema": { "type": "string", "description": "Comma-separated media types; each value one of: image, video, audio, gif, document.", "examples": [ "image,video" ] }, "required": false, "description": "Comma-separated media types; each value one of: image, video, audio, gif, document." }, { "name": "filter[enrichmentStatus]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI enrichment statuses; each value one of: pending, processing, completed, failed.", "examples": [ "completed" ] }, "required": false, "description": "Comma-separated AI enrichment statuses; each value one of: pending, processing, completed, failed." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "postType", "artifactKind", "title", "status", "workflowStatusId", "text", "assetIds", "media", "assetTags", "userTags", "assignees", "contentPayloadId", "latestScheduledPost", "scheduledDestinationAccountIds", "draftDestinationAccountIds", "saveDestination", "saveMessage", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "UUID of the post.", "examples": [ "3c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "postType": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel" ], "description": "Content format of a post: text_post (text only), text_image, text_video, or carousel (2+ photos).", "examples": [ "text_post", "text_image" ] }, "artifactKind": { "anyOf": [ { "type": "string", "enum": [ "slideshow", "image_meme", "green_screen_meme" ] }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "idea", "proposed_render", "draft", "in_review", "approved", "rejected", "archived", "deleted" ], "description": "Editorial status of a post: idea, proposed_render, draft, approved, rejected, archived, or deleted.", "examples": [ "draft", "approved" ] }, "workflowStatusId": { "type": "string", "description": "Workspace-defined content workflow status currently assigned to the post.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "text": { "type": "string" }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "media": { "type": "array", "items": { "type": "object", "required": [ "assetId", "mimeType", "displayName", "thumbnailPath" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "displayName": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Display metadata (mime type, name, thumbnail path) for the post's media, in the same order as assetIds. Empty for text-only posts." }, "assetTags": { "type": "array", "items": { "type": "string" }, "description": "Deduped, sorted union of the post's non-deleted assets' AI tags; empty for text-only posts.", "examples": [ [ "launch", "product" ] ] }, "userTags": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "colour" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" } }, "additionalProperties": false }, "description": "User/agent-assigned registry tags (id, name, colour) on the post; distinct from AI-derived assetTags. Empty when no tags are assigned." }, "assignees": { "type": "array", "items": { "type": "object", "required": [ "userId", "name", "email" ], "properties": { "userId": { "$ref": "#/components/schemas/UUID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Team members assigned to the post (userId plus display name/email), in assignment order. Empty when unassigned. Set via the setPostAssignees endpoint." }, "postInput": { "anyOf": [ { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "posts" ], "properties": { "kind": { "type": "string", "enum": [ "thread" ] }, "posts": { "type": "array", "items": { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, "description": "an array of at least 2 item(s)", "title": "minItems(2)", "minItems": 2 } }, "additionalProperties": false } ] }, "postPublishActions": { "type": "object", "required": [], "properties": { "firstComment": { "anyOf": [ { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false }, { "type": "null" } ] }, "engagementCommentTrigger": { "anyOf": [ { "type": "object", "required": [ "likeThreshold", "windowHours", "comment" ], "properties": { "likeThreshold": { "$ref": "#/components/schemas/Int", "description": "a number greater than or equal to 1", "title": "greaterThanOrEqualTo(1)", "minimum": 1 }, "windowHours": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 720", "title": "between(1, 720)", "minimum": 1, "maximum": 720 }, "comment": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "null" } ] }, "repostAfter": { "anyOf": [ { "type": "object", "required": [ "offsetDays", "mode" ], "properties": { "offsetDays": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 30", "title": "between(1, 30)", "minimum": 1, "maximum": 30 }, "mode": { "type": "string", "enum": [ "retweet", "quote" ] }, "text": { "type": "string" } }, "additionalProperties": false, "description": "Repost the published post offsetDays (1 to 30) after publish, either as a plain retweet or a quote (text required for quote mode)." }, { "type": "null" } ] }, "recurrenceIntervalDays": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 365", "title": "between(1, 365)", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "recurrenceEndsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "contentPayloadId": { "$ref": "#/components/schemas/UUID" }, "latestScheduledPost": { "anyOf": [ { "type": "object", "required": [ "id", "teamId", "contentItemId", "socialAccountId", "provider", "status", "scheduledAt", "timezone", "platformPostId", "platformSettings", "publishResults", "providerPublishState", "errorCode", "errorMessage", "errorCategory", "workflowId", "workflowRunId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "UUID of this scheduled post (one per target social account).", "examples": [ "7f3a2b10-9c4d-4e5f-8a6b-1c2d3e4f5a6b" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "socialAccountId": { "$ref": "#/components/schemas/UUID" }, "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "failed", "cancelled" ], "description": "Lifecycle status of a scheduled post: draft, scheduled, publishing, published, failed, or cancelled.", "examples": [ "scheduled", "published" ] }, "scheduledAt": { "type": "string", "description": "ISO 8601 timestamp the post is or was due to publish.", "examples": [ "2026-06-15T09:00:00.000Z" ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone name the schedule was chosen in, or null when not recorded.", "examples": [ "Europe/London" ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformSettings": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "publishResults": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "providerPublishState": { "type": "object", "required": [ "provider", "status", "requiresPolling", "publishId", "platformPostId", "providerStatus", "pollingReason", "uploadProgress", "failureCode", "failureCategory" ], "properties": { "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "not_started", "pending", "published", "failed", "unknown" ] }, "requiresPolling": { "type": "boolean" }, "publishId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pollingReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "uploadProgress": { "anyOf": [ { "type": "object", "required": [ "nextByteStart", "uploadSize" ], "properties": { "nextByteStart": { "type": "number" }, "uploadSize": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] } }, "additionalProperties": false }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] }, "workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "scheduledDestinationAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "draftDestinationAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "UUIDs of the social accounts selected for this draft. Empty clears the saved selection and duplicates are rejected.", "examples": [ [ "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" ] ] }, "saveDestination": { "type": "string", "enum": [ "queue", "drafts" ] }, "saveMessage": { "type": "string", "enum": [ "Saved to Queue", "Saved to Drafts" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List a team's posts with cursor pagination, newest first by default. Filter by status, provider, scheduled window, free-text search, and enrichment facets; combine filters to narrow results. Use this to find a post id before scheduling, publishing, updating, or deleting.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.listPosts({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.list_posts(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark posts list \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List posts", "x-displayName": "List posts" }, "post": { "tags": [ "Posts" ], "operationId": "social.createPost", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "postType", "artifactKind", "title", "status", "workflowStatusId", "text", "assetIds", "media", "assetTags", "userTags", "assignees", "contentPayloadId", "latestScheduledPost", "scheduledDestinationAccountIds", "draftDestinationAccountIds", "saveDestination", "saveMessage", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "UUID of the post.", "examples": [ "3c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "postType": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel" ], "description": "Content format of a post: text_post (text only), text_image, text_video, or carousel (2+ photos).", "examples": [ "text_post", "text_image" ] }, "artifactKind": { "anyOf": [ { "type": "string", "enum": [ "slideshow", "image_meme", "green_screen_meme" ] }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "idea", "proposed_render", "draft", "in_review", "approved", "rejected", "archived", "deleted" ], "description": "Editorial status of a post: idea, proposed_render, draft, approved, rejected, archived, or deleted.", "examples": [ "draft", "approved" ] }, "workflowStatusId": { "type": "string", "description": "Workspace-defined content workflow status currently assigned to the post.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "text": { "type": "string" }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "media": { "type": "array", "items": { "type": "object", "required": [ "assetId", "mimeType", "displayName", "thumbnailPath" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "displayName": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Display metadata (mime type, name, thumbnail path) for the post's media, in the same order as assetIds. Empty for text-only posts." }, "assetTags": { "type": "array", "items": { "type": "string" }, "description": "Deduped, sorted union of the post's non-deleted assets' AI tags; empty for text-only posts.", "examples": [ [ "launch", "product" ] ] }, "userTags": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "colour" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" } }, "additionalProperties": false }, "description": "User/agent-assigned registry tags (id, name, colour) on the post; distinct from AI-derived assetTags. Empty when no tags are assigned." }, "assignees": { "type": "array", "items": { "type": "object", "required": [ "userId", "name", "email" ], "properties": { "userId": { "$ref": "#/components/schemas/UUID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Team members assigned to the post (userId plus display name/email), in assignment order. Empty when unassigned. Set via the setPostAssignees endpoint." }, "postInput": { "anyOf": [ { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "posts" ], "properties": { "kind": { "type": "string", "enum": [ "thread" ] }, "posts": { "type": "array", "items": { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, "description": "an array of at least 2 item(s)", "title": "minItems(2)", "minItems": 2 } }, "additionalProperties": false } ] }, "postPublishActions": { "type": "object", "required": [], "properties": { "firstComment": { "anyOf": [ { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false }, { "type": "null" } ] }, "engagementCommentTrigger": { "anyOf": [ { "type": "object", "required": [ "likeThreshold", "windowHours", "comment" ], "properties": { "likeThreshold": { "$ref": "#/components/schemas/Int", "description": "a number greater than or equal to 1", "title": "greaterThanOrEqualTo(1)", "minimum": 1 }, "windowHours": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 720", "title": "between(1, 720)", "minimum": 1, "maximum": 720 }, "comment": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "null" } ] }, "repostAfter": { "anyOf": [ { "type": "object", "required": [ "offsetDays", "mode" ], "properties": { "offsetDays": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 30", "title": "between(1, 30)", "minimum": 1, "maximum": 30 }, "mode": { "type": "string", "enum": [ "retweet", "quote" ] }, "text": { "type": "string" } }, "additionalProperties": false, "description": "Repost the published post offsetDays (1 to 30) after publish, either as a plain retweet or a quote (text required for quote mode)." }, { "type": "null" } ] }, "recurrenceIntervalDays": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 365", "title": "between(1, 365)", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "recurrenceEndsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "contentPayloadId": { "$ref": "#/components/schemas/UUID" }, "latestScheduledPost": { "anyOf": [ { "type": "object", "required": [ "id", "teamId", "contentItemId", "socialAccountId", "provider", "status", "scheduledAt", "timezone", "platformPostId", "platformSettings", "publishResults", "providerPublishState", "errorCode", "errorMessage", "errorCategory", "workflowId", "workflowRunId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "UUID of this scheduled post (one per target social account).", "examples": [ "7f3a2b10-9c4d-4e5f-8a6b-1c2d3e4f5a6b" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "socialAccountId": { "$ref": "#/components/schemas/UUID" }, "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "failed", "cancelled" ], "description": "Lifecycle status of a scheduled post: draft, scheduled, publishing, published, failed, or cancelled.", "examples": [ "scheduled", "published" ] }, "scheduledAt": { "type": "string", "description": "ISO 8601 timestamp the post is or was due to publish.", "examples": [ "2026-06-15T09:00:00.000Z" ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone name the schedule was chosen in, or null when not recorded.", "examples": [ "Europe/London" ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformSettings": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "publishResults": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "providerPublishState": { "type": "object", "required": [ "provider", "status", "requiresPolling", "publishId", "platformPostId", "providerStatus", "pollingReason", "uploadProgress", "failureCode", "failureCategory" ], "properties": { "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "not_started", "pending", "published", "failed", "unknown" ] }, "requiresPolling": { "type": "boolean" }, "publishId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pollingReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "uploadProgress": { "anyOf": [ { "type": "object", "required": [ "nextByteStart", "uploadSize" ], "properties": { "nextByteStart": { "type": "number" }, "uploadSize": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] } }, "additionalProperties": false }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] }, "workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "scheduledDestinationAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "draftDestinationAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "UUIDs of the social accounts selected for this draft. Empty clears the saved selection and duplicates are rejected.", "examples": [ [ "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" ] ] }, "saveDestination": { "type": "string", "enum": [ "queue", "drafts" ] }, "saveMessage": { "type": "string", "enum": [ "Saved to Queue", "Saved to Drafts" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create a draft post and atomically persist its content, workflow status, assignees, and user tags. Nothing is published by this call: the post stays in draft until you call schedulePost or postNow with target social accounts. Send an Idempotency-Key header so an ambiguous retry replays the original create; reusing the key with a different payload is rejected.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Internal display title for the post; null clears it. Not published to the platform.", "examples": [ "June launch teaser" ] }, "postType": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel" ], "description": "Content format of the post; defaults to text_post.", "examples": [ "text_post" ] }, "text": { "type": "string", "description": "Body text of the post; for thread posts use postInput instead.", "examples": [ "Shipping day! Here is what is new in v1." ] }, "postInput": { "anyOf": [ { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "posts" ], "properties": { "kind": { "type": "string", "enum": [ "thread" ] }, "posts": { "type": "array", "items": { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, "description": "an array of at least 2 item(s)", "title": "minItems(2)", "minItems": 2 } }, "additionalProperties": false } ], "description": "Structured content: an atomic post (text plus optional media/link attachments) or a thread of 2 or more atomic posts. Takes precedence over text." }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "UUIDs of previously uploaded media assets to attach to the post.", "examples": [ [ "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" ] ] }, "postPublishActions": { "type": "object", "required": [], "properties": { "firstComment": { "anyOf": [ { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false }, { "type": "null" } ] }, "engagementCommentTrigger": { "anyOf": [ { "type": "object", "required": [ "likeThreshold", "windowHours", "comment" ], "properties": { "likeThreshold": { "$ref": "#/components/schemas/Int", "description": "a number greater than or equal to 1", "title": "greaterThanOrEqualTo(1)", "minimum": 1 }, "windowHours": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 720", "title": "between(1, 720)", "minimum": 1, "maximum": 720 }, "comment": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "null" } ] }, "repostAfter": { "anyOf": [ { "type": "object", "required": [ "offsetDays", "mode" ], "properties": { "offsetDays": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 30", "title": "between(1, 30)", "minimum": 1, "maximum": 30 }, "mode": { "type": "string", "enum": [ "retweet", "quote" ] }, "text": { "type": "string" } }, "additionalProperties": false, "description": "Repost the published post offsetDays (1 to 30) after publish, either as a plain retweet or a quote (text required for quote mode)." }, { "type": "null" } ] }, "recurrenceIntervalDays": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 365", "title": "between(1, 365)", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "recurrenceEndsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Saved after-publish automations (first comment, engagement-triggered comment, repost, recurrence) applied when the post is scheduled or published." }, "draftDestinationAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "UUIDs of the social accounts selected for this draft. Empty clears the saved selection and duplicates are rejected.", "examples": [ [ "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" ] ] }, "workflowStatusId": { "type": "string", "description": "Team-owned content workflow status to assign atomically with the post save.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "assigneeUserIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Full replacement set of team-member user ids assigned to the post. Empty clears every assignee." }, "userTagSelections": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "id" ], "properties": { "kind": { "type": "string", "enum": [ "existing" ] }, "id": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "name", "colour" ], "properties": { "kind": { "type": "string", "enum": [ "new" ] }, "name": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "colour": { "type": "string", "description": "a string at most 32 character(s) long", "title": "maxLength(32)", "minLength": 1, "maxLength": 32 } }, "additionalProperties": false } ] }, "description": "Full replacement set of existing or inline-created user tags. Empty clears every user-tag assignment." }, "sourceIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Content source UUIDs this post was generated from. Records post-from-source provenance that drives each source's usedCount (deduplicated per post; every id must belong to the team or the create is rejected). When generating posts from sources, pass the ids of the sources actually used so least-used source rotation stays accurate.", "examples": [ [ "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" ] ] } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.createPost({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.create_post(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark posts create \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create post", "x-displayName": "Create post" } }, "/v1/teams/{teamId}/posts/{postId}": { "get": { "tags": [ "Posts" ], "operationId": "social.getPost", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "postType", "artifactKind", "title", "status", "workflowStatusId", "text", "assetIds", "media", "assetTags", "userTags", "assignees", "contentPayloadId", "latestScheduledPost", "scheduledDestinationAccountIds", "draftDestinationAccountIds", "saveDestination", "saveMessage", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "UUID of the post.", "examples": [ "3c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "postType": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel" ], "description": "Content format of a post: text_post (text only), text_image, text_video, or carousel (2+ photos).", "examples": [ "text_post", "text_image" ] }, "artifactKind": { "anyOf": [ { "type": "string", "enum": [ "slideshow", "image_meme", "green_screen_meme" ] }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "idea", "proposed_render", "draft", "in_review", "approved", "rejected", "archived", "deleted" ], "description": "Editorial status of a post: idea, proposed_render, draft, approved, rejected, archived, or deleted.", "examples": [ "draft", "approved" ] }, "workflowStatusId": { "type": "string", "description": "Workspace-defined content workflow status currently assigned to the post.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "text": { "type": "string" }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "media": { "type": "array", "items": { "type": "object", "required": [ "assetId", "mimeType", "displayName", "thumbnailPath" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "displayName": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Display metadata (mime type, name, thumbnail path) for the post's media, in the same order as assetIds. Empty for text-only posts." }, "assetTags": { "type": "array", "items": { "type": "string" }, "description": "Deduped, sorted union of the post's non-deleted assets' AI tags; empty for text-only posts.", "examples": [ [ "launch", "product" ] ] }, "userTags": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "colour" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" } }, "additionalProperties": false }, "description": "User/agent-assigned registry tags (id, name, colour) on the post; distinct from AI-derived assetTags. Empty when no tags are assigned." }, "assignees": { "type": "array", "items": { "type": "object", "required": [ "userId", "name", "email" ], "properties": { "userId": { "$ref": "#/components/schemas/UUID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Team members assigned to the post (userId plus display name/email), in assignment order. Empty when unassigned. Set via the setPostAssignees endpoint." }, "postInput": { "anyOf": [ { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "posts" ], "properties": { "kind": { "type": "string", "enum": [ "thread" ] }, "posts": { "type": "array", "items": { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, "description": "an array of at least 2 item(s)", "title": "minItems(2)", "minItems": 2 } }, "additionalProperties": false } ] }, "postPublishActions": { "type": "object", "required": [], "properties": { "firstComment": { "anyOf": [ { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false }, { "type": "null" } ] }, "engagementCommentTrigger": { "anyOf": [ { "type": "object", "required": [ "likeThreshold", "windowHours", "comment" ], "properties": { "likeThreshold": { "$ref": "#/components/schemas/Int", "description": "a number greater than or equal to 1", "title": "greaterThanOrEqualTo(1)", "minimum": 1 }, "windowHours": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 720", "title": "between(1, 720)", "minimum": 1, "maximum": 720 }, "comment": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "null" } ] }, "repostAfter": { "anyOf": [ { "type": "object", "required": [ "offsetDays", "mode" ], "properties": { "offsetDays": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 30", "title": "between(1, 30)", "minimum": 1, "maximum": 30 }, "mode": { "type": "string", "enum": [ "retweet", "quote" ] }, "text": { "type": "string" } }, "additionalProperties": false, "description": "Repost the published post offsetDays (1 to 30) after publish, either as a plain retweet or a quote (text required for quote mode)." }, { "type": "null" } ] }, "recurrenceIntervalDays": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 365", "title": "between(1, 365)", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "recurrenceEndsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "contentPayloadId": { "$ref": "#/components/schemas/UUID" }, "latestScheduledPost": { "anyOf": [ { "type": "object", "required": [ "id", "teamId", "contentItemId", "socialAccountId", "provider", "status", "scheduledAt", "timezone", "platformPostId", "platformSettings", "publishResults", "providerPublishState", "errorCode", "errorMessage", "errorCategory", "workflowId", "workflowRunId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "UUID of this scheduled post (one per target social account).", "examples": [ "7f3a2b10-9c4d-4e5f-8a6b-1c2d3e4f5a6b" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "socialAccountId": { "$ref": "#/components/schemas/UUID" }, "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "failed", "cancelled" ], "description": "Lifecycle status of a scheduled post: draft, scheduled, publishing, published, failed, or cancelled.", "examples": [ "scheduled", "published" ] }, "scheduledAt": { "type": "string", "description": "ISO 8601 timestamp the post is or was due to publish.", "examples": [ "2026-06-15T09:00:00.000Z" ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone name the schedule was chosen in, or null when not recorded.", "examples": [ "Europe/London" ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformSettings": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "publishResults": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "providerPublishState": { "type": "object", "required": [ "provider", "status", "requiresPolling", "publishId", "platformPostId", "providerStatus", "pollingReason", "uploadProgress", "failureCode", "failureCategory" ], "properties": { "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "not_started", "pending", "published", "failed", "unknown" ] }, "requiresPolling": { "type": "boolean" }, "publishId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pollingReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "uploadProgress": { "anyOf": [ { "type": "object", "required": [ "nextByteStart", "uploadSize" ], "properties": { "nextByteStart": { "type": "number" }, "uploadSize": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] } }, "additionalProperties": false }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] }, "workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "scheduledDestinationAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "draftDestinationAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "UUIDs of the social accounts selected for this draft. Empty clears the saved selection and duplicates are rejected.", "examples": [ [ "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" ] ] }, "saveDestination": { "type": "string", "enum": [ "queue", "drafts" ] }, "saveMessage": { "type": "string", "enum": [ "Saved to Queue", "Saved to Drafts" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Fetch a single post by id, including its content, status, scheduling details, and attached assets. Use listPosts to find post ids; use getPostPerformance for the post's published metrics.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.getPost({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.get_post(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark posts get \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Get post", "x-displayName": "Get post" }, "patch": { "tags": [ "Posts" ], "operationId": "social.updatePost", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "postType", "artifactKind", "title", "status", "workflowStatusId", "text", "assetIds", "media", "assetTags", "userTags", "assignees", "contentPayloadId", "latestScheduledPost", "scheduledDestinationAccountIds", "draftDestinationAccountIds", "saveDestination", "saveMessage", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "UUID of the post.", "examples": [ "3c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "postType": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel" ], "description": "Content format of a post: text_post (text only), text_image, text_video, or carousel (2+ photos).", "examples": [ "text_post", "text_image" ] }, "artifactKind": { "anyOf": [ { "type": "string", "enum": [ "slideshow", "image_meme", "green_screen_meme" ] }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "idea", "proposed_render", "draft", "in_review", "approved", "rejected", "archived", "deleted" ], "description": "Editorial status of a post: idea, proposed_render, draft, approved, rejected, archived, or deleted.", "examples": [ "draft", "approved" ] }, "workflowStatusId": { "type": "string", "description": "Workspace-defined content workflow status currently assigned to the post.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "text": { "type": "string" }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "media": { "type": "array", "items": { "type": "object", "required": [ "assetId", "mimeType", "displayName", "thumbnailPath" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "displayName": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Display metadata (mime type, name, thumbnail path) for the post's media, in the same order as assetIds. Empty for text-only posts." }, "assetTags": { "type": "array", "items": { "type": "string" }, "description": "Deduped, sorted union of the post's non-deleted assets' AI tags; empty for text-only posts.", "examples": [ [ "launch", "product" ] ] }, "userTags": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "colour" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" } }, "additionalProperties": false }, "description": "User/agent-assigned registry tags (id, name, colour) on the post; distinct from AI-derived assetTags. Empty when no tags are assigned." }, "assignees": { "type": "array", "items": { "type": "object", "required": [ "userId", "name", "email" ], "properties": { "userId": { "$ref": "#/components/schemas/UUID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Team members assigned to the post (userId plus display name/email), in assignment order. Empty when unassigned. Set via the setPostAssignees endpoint." }, "postInput": { "anyOf": [ { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "posts" ], "properties": { "kind": { "type": "string", "enum": [ "thread" ] }, "posts": { "type": "array", "items": { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, "description": "an array of at least 2 item(s)", "title": "minItems(2)", "minItems": 2 } }, "additionalProperties": false } ] }, "postPublishActions": { "type": "object", "required": [], "properties": { "firstComment": { "anyOf": [ { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false }, { "type": "null" } ] }, "engagementCommentTrigger": { "anyOf": [ { "type": "object", "required": [ "likeThreshold", "windowHours", "comment" ], "properties": { "likeThreshold": { "$ref": "#/components/schemas/Int", "description": "a number greater than or equal to 1", "title": "greaterThanOrEqualTo(1)", "minimum": 1 }, "windowHours": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 720", "title": "between(1, 720)", "minimum": 1, "maximum": 720 }, "comment": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "null" } ] }, "repostAfter": { "anyOf": [ { "type": "object", "required": [ "offsetDays", "mode" ], "properties": { "offsetDays": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 30", "title": "between(1, 30)", "minimum": 1, "maximum": 30 }, "mode": { "type": "string", "enum": [ "retweet", "quote" ] }, "text": { "type": "string" } }, "additionalProperties": false, "description": "Repost the published post offsetDays (1 to 30) after publish, either as a plain retweet or a quote (text required for quote mode)." }, { "type": "null" } ] }, "recurrenceIntervalDays": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 365", "title": "between(1, 365)", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "recurrenceEndsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "contentPayloadId": { "$ref": "#/components/schemas/UUID" }, "latestScheduledPost": { "anyOf": [ { "type": "object", "required": [ "id", "teamId", "contentItemId", "socialAccountId", "provider", "status", "scheduledAt", "timezone", "platformPostId", "platformSettings", "publishResults", "providerPublishState", "errorCode", "errorMessage", "errorCategory", "workflowId", "workflowRunId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "UUID of this scheduled post (one per target social account).", "examples": [ "7f3a2b10-9c4d-4e5f-8a6b-1c2d3e4f5a6b" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "socialAccountId": { "$ref": "#/components/schemas/UUID" }, "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "failed", "cancelled" ], "description": "Lifecycle status of a scheduled post: draft, scheduled, publishing, published, failed, or cancelled.", "examples": [ "scheduled", "published" ] }, "scheduledAt": { "type": "string", "description": "ISO 8601 timestamp the post is or was due to publish.", "examples": [ "2026-06-15T09:00:00.000Z" ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone name the schedule was chosen in, or null when not recorded.", "examples": [ "Europe/London" ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformSettings": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "publishResults": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "providerPublishState": { "type": "object", "required": [ "provider", "status", "requiresPolling", "publishId", "platformPostId", "providerStatus", "pollingReason", "uploadProgress", "failureCode", "failureCategory" ], "properties": { "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "not_started", "pending", "published", "failed", "unknown" ] }, "requiresPolling": { "type": "boolean" }, "publishId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pollingReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "uploadProgress": { "anyOf": [ { "type": "object", "required": [ "nextByteStart", "uploadSize" ], "properties": { "nextByteStart": { "type": "number" }, "uploadSize": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] } }, "additionalProperties": false }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] }, "workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "scheduledDestinationAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "draftDestinationAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "UUIDs of the social accounts selected for this draft. Empty clears the saved selection and duplicates are rejected.", "examples": [ [ "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" ] ] }, "saveDestination": { "type": "string", "enum": [ "queue", "drafts" ] }, "saveMessage": { "type": "string", "enum": [ "Saved to Queue", "Saved to Drafts" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Atomically update a post's content, workflow status, assignees, or user tags. Omitted relation fields are preserved and present empty arrays clear them. expectedContentPayloadId provides optimistic concurrency control. Send an Idempotency-Key header so an ambiguous retry replays the original update; reusing the key with a different payload is rejected. Updating content does not rewrite an existing immutable scheduled snapshot: reschedule it explicitly to publish the new content.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Internal display title for the post; null clears it. Not published to the platform.", "examples": [ "June launch teaser" ] }, "postType": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel" ], "description": "Content format of the post; defaults to text_post.", "examples": [ "text_post" ] }, "text": { "type": "string", "description": "Body text of the post; for thread posts use postInput instead.", "examples": [ "Shipping day! Here is what is new in v1." ] }, "postInput": { "anyOf": [ { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "posts" ], "properties": { "kind": { "type": "string", "enum": [ "thread" ] }, "posts": { "type": "array", "items": { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, "description": "an array of at least 2 item(s)", "title": "minItems(2)", "minItems": 2 } }, "additionalProperties": false } ], "description": "Structured content: an atomic post (text plus optional media/link attachments) or a thread of 2 or more atomic posts. Takes precedence over text." }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "UUIDs of previously uploaded media assets to attach to the post.", "examples": [ [ "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" ] ] }, "postPublishActions": { "type": "object", "required": [], "properties": { "firstComment": { "anyOf": [ { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false }, { "type": "null" } ] }, "engagementCommentTrigger": { "anyOf": [ { "type": "object", "required": [ "likeThreshold", "windowHours", "comment" ], "properties": { "likeThreshold": { "$ref": "#/components/schemas/Int", "description": "a number greater than or equal to 1", "title": "greaterThanOrEqualTo(1)", "minimum": 1 }, "windowHours": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 720", "title": "between(1, 720)", "minimum": 1, "maximum": 720 }, "comment": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "null" } ] }, "repostAfter": { "anyOf": [ { "type": "object", "required": [ "offsetDays", "mode" ], "properties": { "offsetDays": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 30", "title": "between(1, 30)", "minimum": 1, "maximum": 30 }, "mode": { "type": "string", "enum": [ "retweet", "quote" ] }, "text": { "type": "string" } }, "additionalProperties": false, "description": "Repost the published post offsetDays (1 to 30) after publish, either as a plain retweet or a quote (text required for quote mode)." }, { "type": "null" } ] }, "recurrenceIntervalDays": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 365", "title": "between(1, 365)", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "recurrenceEndsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Saved after-publish automations (first comment, engagement-triggered comment, repost, recurrence) applied when the post is scheduled or published." }, "draftDestinationAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "UUIDs of the social accounts selected for this draft. Empty clears the saved selection and duplicates are rejected.", "examples": [ [ "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" ] ] }, "workflowStatusId": { "type": "string", "description": "Team-owned content workflow status to assign atomically with the post save.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "assigneeUserIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Full replacement set of team-member user ids assigned to the post. Empty clears every assignee." }, "userTagSelections": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "id" ], "properties": { "kind": { "type": "string", "enum": [ "existing" ] }, "id": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "name", "colour" ], "properties": { "kind": { "type": "string", "enum": [ "new" ] }, "name": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "colour": { "type": "string", "description": "a string at most 32 character(s) long", "title": "maxLength(32)", "minLength": 1, "maxLength": 32 } }, "additionalProperties": false } ] }, "description": "Full replacement set of existing or inline-created user tags. Empty clears every user-tag assignment." }, "expectedContentPayloadId": { "type": "string", "description": "Optimistic concurrency guard. The update is rejected when this is no longer the post current content payload id.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "expectedUpdatedAt": { "type": "string", "description": "Deprecated and ignored. Accepted for older clients. Item-level fields (title, post type, workflow status, relations) are last-write-wins; content is guarded by expectedContentPayloadId." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.updatePost({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.update_post(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark social update-post \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Update post", "x-displayName": "Update post" }, "delete": { "tags": [ "Posts" ], "operationId": "social.deletePost", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, { "name": "alsoDeleteFromPlatform", "in": "query", "schema": { "type": "string", "description": "Pass \"true\" to also delete the published post from the social platform; any other value (or omission) deletes only the Octospark record.", "default": "false", "examples": [ "true" ] }, "required": false, "description": "Pass \"true\" to also delete the published post from the social platform; any other value (or omission) deletes only the Octospark record." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "platformDelete" ], "properties": { "deleted": { "type": "boolean" }, "platformDelete": { "type": "object", "required": [ "status", "provider", "platformPostId", "message" ], "properties": { "status": { "type": "string", "enum": [ "not_requested", "deleted", "skipped", "failed" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, { "type": "null" } ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Delete a post. By default only the Octospark record is removed; pass the alsoDeleteFromPlatform query flag to also remove the published post from the social provider. To stop a scheduled publish without losing the post, use movePostToDraft instead.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.deletePost({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.delete_post(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark posts delete \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete post", "x-displayName": "Delete post" } }, "/v1/teams/{teamId}/posts/{postId}/schedule": { "post": { "tags": [ "Posts" ], "operationId": "social.schedulePost", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "outcome" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "socialAccountId" ], "properties": { "socialAccountId": { "type": "string", "description": "UUID of the social account this result entry is for.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "scheduledPost": { "type": "object", "required": [ "id", "teamId", "contentItemId", "socialAccountId", "provider", "status", "scheduledAt", "timezone", "platformPostId", "platformSettings", "publishResults", "providerPublishState", "errorCode", "errorMessage", "errorCategory", "workflowId", "workflowRunId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "UUID of this scheduled post (one per target social account).", "examples": [ "7f3a2b10-9c4d-4e5f-8a6b-1c2d3e4f5a6b" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "socialAccountId": { "$ref": "#/components/schemas/UUID" }, "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "failed", "cancelled" ], "description": "Lifecycle status of a scheduled post: draft, scheduled, publishing, published, failed, or cancelled.", "examples": [ "scheduled", "published" ] }, "scheduledAt": { "type": "string", "description": "ISO 8601 timestamp the post is or was due to publish.", "examples": [ "2026-06-15T09:00:00.000Z" ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone name the schedule was chosen in, or null when not recorded.", "examples": [ "Europe/London" ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformSettings": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "publishResults": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "providerPublishState": { "type": "object", "required": [ "provider", "status", "requiresPolling", "publishId", "platformPostId", "providerStatus", "pollingReason", "uploadProgress", "failureCode", "failureCategory" ], "properties": { "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "not_started", "pending", "published", "failed", "unknown" ] }, "requiresPolling": { "type": "boolean" }, "publishId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pollingReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "uploadProgress": { "anyOf": [ { "type": "object", "required": [ "nextByteStart", "uploadSize" ], "properties": { "nextByteStart": { "type": "number" }, "uploadSize": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] } }, "additionalProperties": false }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] }, "workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false, "description": "The scheduled post created for this account; present only when this account succeeded." }, "error": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "code": { "type": "string", "description": "Coarse failure class for this leg (e.g. BAD_REQUEST for a validation rejection, INTERNAL_ERROR for a fault).", "examples": [ "BAD_REQUEST" ] } }, "additionalProperties": false, "description": "Failure detail for this account; present only when this account failed." } }, "additionalProperties": false, "description": "Per-account result envelope: exactly one of scheduledPost (success) or error (failure) is set." }, "description": "One result entry per requested social account, in request order." }, "outcome": { "type": "object", "required": [ "status", "totalCount", "successCount", "failureCount" ], "properties": { "status": { "type": "string", "enum": [ "empty", "all_failed", "partially_failed", "none_failed" ], "description": "Aggregate fan-out outcome: empty (no accounts), all_failed, partially_failed, or none_failed (every account succeeded).", "examples": [ "none_failed" ] }, "totalCount": { "type": "number", "description": "Number of social accounts the post fanned out to.", "examples": [ 3 ] }, "successCount": { "type": "number", "description": "Number of accounts that accepted the publish/schedule request.", "examples": [ 2 ] }, "failureCount": { "type": "number", "description": "Number of accounts that failed.", "examples": [ 1 ] } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Schedule a post for future publishing to one or more social accounts via socialAccountIds. Provide EXACTLY ONE of scheduledAt or useNextSlot=true (supplying both, or neither, is rejected 400 before any credits are reserved). With scheduledAt, the instant must be at least 60 seconds in the future and within the scheduling horizon (otherwise 400). With useNextSlot=true, the server resolves the next unfilled scheduling slot for the target account(s) inside the insert transaction and returns the resolved scheduledAt; if no slot is free within the 90-day horizon it is rejected 409. timezone is an optional IANA name. The call handles each account separately and returns HTTP 200 with one result per account: each entry in data[] is either a scheduledPost or an error (including insufficient credits on costed providers, which reserve credits per account), plus an outcome summary (status, totalCount, successCount, failureCount). Always read the per-account results in the body rather than trusting the status code alone. Send an Idempotency-Key header so timed-out retries replay the original result instead of double-scheduling; use postNow to publish immediately.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "socialAccountIds" ], "properties": { "socialAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "UUIDs of the connected social accounts the post fans out to; at least one is required, duplicates are rejected, and each account gets its own per-account result.", "title": "minItems(1)", "examples": [ [ "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" ] ], "minItems": 1 }, "expectedContentPayloadId": { "type": "string", "description": "Optimistic concurrency pin for the exact saved content payload this terminal delivery intent validated. The composer always supplies it.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "preserveExistingTimes": { "type": "boolean", "description": "When true, retained active destination accounts keep their existing scheduled instants while new accounts use the requested timing and removed accounts are cancelled." }, "scheduledAt": { "type": "string", "description": "ISO 8601 timestamp to publish at; must be at least 60 seconds in the future and within 90 days. Provide EXACTLY ONE of scheduledAt or useNextSlot=true (supplying both, or neither, is rejected with 400).", "examples": [ "2026-06-15T09:00:00Z" ] }, "useNextSlot": { "type": "boolean", "description": "When true, the server resolves the next unfilled scheduling slot for the target account(s) inside the insert transaction and uses it as scheduledAt. Provide EXACTLY ONE of scheduledAt or useNextSlot=true (supplying both, or neither, is rejected with 400).", "examples": [ true ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone name the schedule was chosen in, used for calendar display and (with useNextSlot) slot resolution; scheduledAt itself is absolute.", "examples": [ "Europe/London" ] }, "platformSettings": { "type": "object", "required": [], "properties": { "replySettings": { "anyOf": [ { "type": "string", "enum": [ "following", "mentionedUsers", "subscribers", "verified" ] }, { "type": "null" } ], "description": "X only: who can reply to the published post (following, mentionedUsers, subscribers, or verified). null lets everyone reply." }, "quoteTweetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "X only: id of an existing X post to quote under the new post." }, "visibility": { "anyOf": [ { "type": "string", "enum": [ "PUBLIC", "CONNECTIONS" ] }, { "type": "null" } ], "description": "LinkedIn only: post visibility, PUBLIC or CONNECTIONS. null publishes as PUBLIC." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "LinkedIn, YouTube, and TikTok: title for the published media. Falls back to the first line of the post text where the platform needs one." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube only: video description; falls back to the post text." }, "privacyStatus": { "anyOf": [ { "type": "string", "enum": [ "private", "unlisted", "public" ] }, { "type": "null" } ], "description": "YouTube only: video privacy (private, unlisted, or public). null uploads as private." }, "selfDeclaredMadeForKids": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "YouTube only: marks the video as made for kids (the COPPA self-declaration)." }, "containsSyntheticMedia": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "YouTube only: discloses that the video contains AI-generated or synthetic media." }, "communityGuidelinesConfirmed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "YouTube only: confirms the publisher certifies the upload complies with YouTube Community Guidelines." }, "categoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube only: numeric video category id for the upload." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "YouTube only: tags attached to the uploaded video." }, "thumbnailAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube only: media-library asset id to set as the video thumbnail once the upload succeeds." }, "privacyLevel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TikTok only: privacy level from the account's creator info; valid values vary per account." }, "contentPostingMethod": { "anyOf": [ { "type": "string", "enum": [ "DIRECT_POST", "UPLOAD" ] }, { "type": "null" } ], "description": "TikTok only: DIRECT_POST publishes immediately, UPLOAD sends the post to the creator inbox. null uses DIRECT_POST." }, "mediaTransferMode": { "anyOf": [ { "type": "string", "enum": [ "FILE_UPLOAD", "PULL_FROM_URL" ] }, { "type": "null" } ], "description": "TikTok only: how video bytes reach TikTok (FILE_UPLOAD or PULL_FROM_URL; pull requires a verified HTTPS media URL). Photo posts always pull from URL. null uses FILE_UPLOAD." }, "disableDuet": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: disables duets on the published video." }, "disableComment": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: disables comments on the published post." }, "disableStitch": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: disables stitches on the published video." }, "videoCoverTimestampMs": { "anyOf": [ { "type": "number", "description": "a number between 0 and 2147483647", "title": "between(0, 2147483647)", "minimum": 0, "maximum": 2147483647 }, { "type": "null" } ], "description": "TikTok only: which video frame to use as the cover, in milliseconds from the start." }, "photoCoverIndex": { "anyOf": [ { "type": "number", "description": "a number between 0 and 34", "title": "between(0, 34)", "minimum": 0, "maximum": 34 }, { "type": "null" } ], "description": "TikTok only: zero-based index of the photo to use as the cover of a photo post." }, "autoAddMusic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: let TikTok add recommended music to a photo post (the creator can change the track later). A feature toggle, separate from the music rights confirmation." }, "musicUsageRightsConfirmed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: confirms the publisher holds usage rights for any music in the post. Never assumed; set it explicitly." }, "brandedContent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: discloses the post as paid branded content." }, "brandOrganic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: discloses the post as organic brand content (promoting your own business)." }, "isAigc": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: discloses AI-generated video content." }, "linkUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Facebook only: link to attach to a Page text post." }, "replyControl": { "anyOf": [ { "type": "string", "enum": [ "everyone", "accounts_you_follow", "mentioned_only", "parent_post_author_only", "followers_only" ] }, { "type": "null" } ], "description": "Threads only: who can reply to the root post. null uses the account default." }, "topicTag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Threads only: topic tag attached to the post." }, "quotePostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Threads only: id of an existing Threads post to quote." }, "crossReshareToInstagram": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Threads only: also reshare the published post to Instagram." }, "boardId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pinterest only: id of the public board this Pin is saved to. Defaults to the board captured when the account was connected." }, "pinTitle": { "anyOf": [ { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "maxLength": 100 }, { "type": "null" } ], "description": "Pinterest only: Pin title, max 100 characters. Falls back to the first line of the post text." }, "pinDescription": { "anyOf": [ { "type": "string", "description": "a string at most 800 character(s) long", "title": "maxLength(800)", "maxLength": 800 }, { "type": "null" } ], "description": "Pinterest only: Pin description, max 800 characters. Falls back to the post text." }, "destinationLink": { "anyOf": [ { "type": "string", "description": "a string at most 2048 character(s) long", "title": "maxLength(2048)", "maxLength": 2048 }, { "type": "null" } ], "description": "Pinterest only: outbound link the Pin drives traffic to, max 2048 characters. Never shortened." }, "altText": { "anyOf": [ { "type": "string", "description": "a string at most 500 character(s) long", "title": "maxLength(500)", "maxLength": 500 }, { "type": "null" } ], "description": "Pinterest only: alt text for accessibility, max 500 characters." }, "coverImageAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pinterest only: media-library asset id used as the video Pin cover. When absent, Pinterest extracts the first frame." }, "aiDisclosure": { "anyOf": [ { "type": "string", "enum": [ "ai_modified", "synthetic_performer" ] }, { "type": "null" } ], "description": "Pinterest only: manual AI disclosure for uploaded media. Octospark-generated media is declared automatically from provenance." } }, "additionalProperties": false, "description": "Provider-specific publish settings. Each field applies to one provider (named in its description) and is ignored by accounts on other providers, so a single object can carry settings for every account the post targets. Unknown keys are rejected.", "examples": [ { "replySettings": "following" } ] }, "platformSettingsBySocialAccountId": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "type": "object", "required": [], "properties": { "replySettings": { "anyOf": [ { "type": "string", "enum": [ "following", "mentionedUsers", "subscribers", "verified" ] }, { "type": "null" } ], "description": "X only: who can reply to the published post (following, mentionedUsers, subscribers, or verified). null lets everyone reply." }, "quoteTweetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "X only: id of an existing X post to quote under the new post." }, "visibility": { "anyOf": [ { "type": "string", "enum": [ "PUBLIC", "CONNECTIONS" ] }, { "type": "null" } ], "description": "LinkedIn only: post visibility, PUBLIC or CONNECTIONS. null publishes as PUBLIC." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "LinkedIn, YouTube, and TikTok: title for the published media. Falls back to the first line of the post text where the platform needs one." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube only: video description; falls back to the post text." }, "privacyStatus": { "anyOf": [ { "type": "string", "enum": [ "private", "unlisted", "public" ] }, { "type": "null" } ], "description": "YouTube only: video privacy (private, unlisted, or public). null uploads as private." }, "selfDeclaredMadeForKids": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "YouTube only: marks the video as made for kids (the COPPA self-declaration)." }, "containsSyntheticMedia": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "YouTube only: discloses that the video contains AI-generated or synthetic media." }, "communityGuidelinesConfirmed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "YouTube only: confirms the publisher certifies the upload complies with YouTube Community Guidelines." }, "categoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube only: numeric video category id for the upload." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "YouTube only: tags attached to the uploaded video." }, "thumbnailAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube only: media-library asset id to set as the video thumbnail once the upload succeeds." }, "privacyLevel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TikTok only: privacy level from the account's creator info; valid values vary per account." }, "contentPostingMethod": { "anyOf": [ { "type": "string", "enum": [ "DIRECT_POST", "UPLOAD" ] }, { "type": "null" } ], "description": "TikTok only: DIRECT_POST publishes immediately, UPLOAD sends the post to the creator inbox. null uses DIRECT_POST." }, "mediaTransferMode": { "anyOf": [ { "type": "string", "enum": [ "FILE_UPLOAD", "PULL_FROM_URL" ] }, { "type": "null" } ], "description": "TikTok only: how video bytes reach TikTok (FILE_UPLOAD or PULL_FROM_URL; pull requires a verified HTTPS media URL). Photo posts always pull from URL. null uses FILE_UPLOAD." }, "disableDuet": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: disables duets on the published video." }, "disableComment": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: disables comments on the published post." }, "disableStitch": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: disables stitches on the published video." }, "videoCoverTimestampMs": { "anyOf": [ { "type": "number", "description": "a number between 0 and 2147483647", "title": "between(0, 2147483647)", "minimum": 0, "maximum": 2147483647 }, { "type": "null" } ], "description": "TikTok only: which video frame to use as the cover, in milliseconds from the start." }, "photoCoverIndex": { "anyOf": [ { "type": "number", "description": "a number between 0 and 34", "title": "between(0, 34)", "minimum": 0, "maximum": 34 }, { "type": "null" } ], "description": "TikTok only: zero-based index of the photo to use as the cover of a photo post." }, "autoAddMusic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: let TikTok add recommended music to a photo post (the creator can change the track later). A feature toggle, separate from the music rights confirmation." }, "musicUsageRightsConfirmed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: confirms the publisher holds usage rights for any music in the post. Never assumed; set it explicitly." }, "brandedContent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: discloses the post as paid branded content." }, "brandOrganic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: discloses the post as organic brand content (promoting your own business)." }, "isAigc": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: discloses AI-generated video content." }, "linkUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Facebook only: link to attach to a Page text post." }, "replyControl": { "anyOf": [ { "type": "string", "enum": [ "everyone", "accounts_you_follow", "mentioned_only", "parent_post_author_only", "followers_only" ] }, { "type": "null" } ], "description": "Threads only: who can reply to the root post. null uses the account default." }, "topicTag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Threads only: topic tag attached to the post." }, "quotePostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Threads only: id of an existing Threads post to quote." }, "crossReshareToInstagram": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Threads only: also reshare the published post to Instagram." }, "boardId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pinterest only: id of the public board this Pin is saved to. Defaults to the board captured when the account was connected." }, "pinTitle": { "anyOf": [ { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "maxLength": 100 }, { "type": "null" } ], "description": "Pinterest only: Pin title, max 100 characters. Falls back to the first line of the post text." }, "pinDescription": { "anyOf": [ { "type": "string", "description": "a string at most 800 character(s) long", "title": "maxLength(800)", "maxLength": 800 }, { "type": "null" } ], "description": "Pinterest only: Pin description, max 800 characters. Falls back to the post text." }, "destinationLink": { "anyOf": [ { "type": "string", "description": "a string at most 2048 character(s) long", "title": "maxLength(2048)", "maxLength": 2048 }, { "type": "null" } ], "description": "Pinterest only: outbound link the Pin drives traffic to, max 2048 characters. Never shortened." }, "altText": { "anyOf": [ { "type": "string", "description": "a string at most 500 character(s) long", "title": "maxLength(500)", "maxLength": 500 }, { "type": "null" } ], "description": "Pinterest only: alt text for accessibility, max 500 characters." }, "coverImageAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pinterest only: media-library asset id used as the video Pin cover. When absent, Pinterest extracts the first frame." }, "aiDisclosure": { "anyOf": [ { "type": "string", "enum": [ "ai_modified", "synthetic_performer" ] }, { "type": "null" } ], "description": "Pinterest only: manual AI disclosure for uploaded media. Octospark-generated media is declared automatically from provenance." } }, "additionalProperties": false, "description": "Provider-specific publish settings. Each field applies to one provider (named in its description) and is ignored by accounts on other providers, so a single object can carry settings for every account the post targets. Unknown keys are rejected.", "examples": [ { "replySettings": "following" } ] }, "description": "Per-account overrides of the shared platform settings, keyed by social account UUID; values merge over platformSettings for that account." }, "overrideApproval": { "type": "boolean", "description": "When the workspace postApprovalMode is required, bypasses the client-approval gate for this call. Requires team admin permission (manage-level); the override is audited as an internal approval decision.", "examples": [ true ] }, "textBySocialAccountId": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "type": "string" }, "description": "Per-account body-text overrides, keyed by social account UUID. An entry replaces the post's shared text for that account's leg only; accounts without an entry publish the shared text. Text-only: media attachments and platform settings are unaffected, and thread posts reject overrides. Entries must be non-blank." }, "firstComment": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false, "description": "Comment to post on the published post immediately after it goes live." }, "engagementCommentTrigger": { "type": "object", "required": [ "likeThreshold", "windowHours", "comment" ], "properties": { "likeThreshold": { "$ref": "#/components/schemas/Int", "description": "a number greater than or equal to 1", "title": "greaterThanOrEqualTo(1)", "minimum": 1 }, "windowHours": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 720", "title": "between(1, 720)", "minimum": 1, "maximum": 720 }, "comment": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Comment to post once the published post reaches likeThreshold likes within windowHours (1 to 720 hours)." }, "repostAfter": { "type": "object", "required": [ "offsetDays", "mode" ], "properties": { "offsetDays": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 30", "title": "between(1, 30)", "minimum": 1, "maximum": 30 }, "mode": { "type": "string", "enum": [ "retweet", "quote" ] }, "text": { "type": "string" } }, "additionalProperties": false, "description": "Repost the published post offsetDays (1 to 30) after publish, either as a plain retweet or a quote (text required for quote mode)." }, "recurrenceIntervalDays": { "$ref": "#/components/schemas/Int", "description": "Republish the post every N days (1 to 365) until recurrenceEndsAt.", "title": "between(1, 365)", "examples": [ 7 ], "minimum": 1, "maximum": 365 }, "recurrenceEndsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp after which the recurrence stops; null means no end date.", "examples": [ "2026-09-01T00:00:00Z" ] } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.schedulePost({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.schedule_post(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark posts schedule \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/schedule\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/schedule';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Schedule post", "x-displayName": "Schedule post" } }, "/v1/teams/{teamId}/posts/{postId}/post-now": { "post": { "tags": [ "Posts" ], "operationId": "social.postNow", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "outcome" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "socialAccountId" ], "properties": { "socialAccountId": { "type": "string", "description": "UUID of the social account this result entry is for.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "scheduledPost": { "type": "object", "required": [ "id", "teamId", "contentItemId", "socialAccountId", "provider", "status", "scheduledAt", "timezone", "platformPostId", "platformSettings", "publishResults", "providerPublishState", "errorCode", "errorMessage", "errorCategory", "workflowId", "workflowRunId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "UUID of this scheduled post (one per target social account).", "examples": [ "7f3a2b10-9c4d-4e5f-8a6b-1c2d3e4f5a6b" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "socialAccountId": { "$ref": "#/components/schemas/UUID" }, "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "failed", "cancelled" ], "description": "Lifecycle status of a scheduled post: draft, scheduled, publishing, published, failed, or cancelled.", "examples": [ "scheduled", "published" ] }, "scheduledAt": { "type": "string", "description": "ISO 8601 timestamp the post is or was due to publish.", "examples": [ "2026-06-15T09:00:00.000Z" ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone name the schedule was chosen in, or null when not recorded.", "examples": [ "Europe/London" ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformSettings": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "publishResults": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "providerPublishState": { "type": "object", "required": [ "provider", "status", "requiresPolling", "publishId", "platformPostId", "providerStatus", "pollingReason", "uploadProgress", "failureCode", "failureCategory" ], "properties": { "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "not_started", "pending", "published", "failed", "unknown" ] }, "requiresPolling": { "type": "boolean" }, "publishId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pollingReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "uploadProgress": { "anyOf": [ { "type": "object", "required": [ "nextByteStart", "uploadSize" ], "properties": { "nextByteStart": { "type": "number" }, "uploadSize": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] } }, "additionalProperties": false }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] }, "workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false, "description": "The scheduled post created for this account; present only when this account succeeded." }, "error": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "code": { "type": "string", "description": "Coarse failure class for this leg (e.g. BAD_REQUEST for a validation rejection, INTERNAL_ERROR for a fault).", "examples": [ "BAD_REQUEST" ] } }, "additionalProperties": false, "description": "Failure detail for this account; present only when this account failed." } }, "additionalProperties": false, "description": "Per-account result envelope: exactly one of scheduledPost (success) or error (failure) is set." }, "description": "One result entry per requested social account, in request order." }, "outcome": { "type": "object", "required": [ "status", "totalCount", "successCount", "failureCount" ], "properties": { "status": { "type": "string", "enum": [ "empty", "all_failed", "partially_failed", "none_failed" ], "description": "Aggregate fan-out outcome: empty (no accounts), all_failed, partially_failed, or none_failed (every account succeeded).", "examples": [ "none_failed" ] }, "totalCount": { "type": "number", "description": "Number of social accounts the post fanned out to.", "examples": [ 3 ] }, "successCount": { "type": "number", "description": "Number of accounts that accepted the publish/schedule request.", "examples": [ 2 ] }, "failureCount": { "type": "number", "description": "Number of accounts that failed.", "examples": [ 1 ] } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Publish a post immediately to one or more social accounts via socialAccountIds. The call handles each account separately and returns HTTP 200 with one result per account: each entry in data[] is either a scheduledPost or an error (including insufficient credits on costed providers, which reserve credits per account), plus an outcome summary (status, totalCount, successCount, failureCount). Always read the per-account results in the body rather than trusting the status code alone. Send an Idempotency-Key header so timed-out retries replay the original result instead of double-publishing; use schedulePost to publish at a future time instead.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "socialAccountIds" ], "properties": { "socialAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "UUIDs of the connected social accounts the post fans out to; at least one is required, duplicates are rejected, and each account gets its own per-account result.", "title": "minItems(1)", "examples": [ [ "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" ] ], "minItems": 1 }, "expectedContentPayloadId": { "type": "string", "description": "Optimistic concurrency pin for the exact saved content payload this terminal delivery intent validated. The composer always supplies it.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "platformSettings": { "type": "object", "required": [], "properties": { "replySettings": { "anyOf": [ { "type": "string", "enum": [ "following", "mentionedUsers", "subscribers", "verified" ] }, { "type": "null" } ], "description": "X only: who can reply to the published post (following, mentionedUsers, subscribers, or verified). null lets everyone reply." }, "quoteTweetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "X only: id of an existing X post to quote under the new post." }, "visibility": { "anyOf": [ { "type": "string", "enum": [ "PUBLIC", "CONNECTIONS" ] }, { "type": "null" } ], "description": "LinkedIn only: post visibility, PUBLIC or CONNECTIONS. null publishes as PUBLIC." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "LinkedIn, YouTube, and TikTok: title for the published media. Falls back to the first line of the post text where the platform needs one." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube only: video description; falls back to the post text." }, "privacyStatus": { "anyOf": [ { "type": "string", "enum": [ "private", "unlisted", "public" ] }, { "type": "null" } ], "description": "YouTube only: video privacy (private, unlisted, or public). null uploads as private." }, "selfDeclaredMadeForKids": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "YouTube only: marks the video as made for kids (the COPPA self-declaration)." }, "containsSyntheticMedia": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "YouTube only: discloses that the video contains AI-generated or synthetic media." }, "communityGuidelinesConfirmed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "YouTube only: confirms the publisher certifies the upload complies with YouTube Community Guidelines." }, "categoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube only: numeric video category id for the upload." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "YouTube only: tags attached to the uploaded video." }, "thumbnailAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube only: media-library asset id to set as the video thumbnail once the upload succeeds." }, "privacyLevel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TikTok only: privacy level from the account's creator info; valid values vary per account." }, "contentPostingMethod": { "anyOf": [ { "type": "string", "enum": [ "DIRECT_POST", "UPLOAD" ] }, { "type": "null" } ], "description": "TikTok only: DIRECT_POST publishes immediately, UPLOAD sends the post to the creator inbox. null uses DIRECT_POST." }, "mediaTransferMode": { "anyOf": [ { "type": "string", "enum": [ "FILE_UPLOAD", "PULL_FROM_URL" ] }, { "type": "null" } ], "description": "TikTok only: how video bytes reach TikTok (FILE_UPLOAD or PULL_FROM_URL; pull requires a verified HTTPS media URL). Photo posts always pull from URL. null uses FILE_UPLOAD." }, "disableDuet": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: disables duets on the published video." }, "disableComment": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: disables comments on the published post." }, "disableStitch": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: disables stitches on the published video." }, "videoCoverTimestampMs": { "anyOf": [ { "type": "number", "description": "a number between 0 and 2147483647", "title": "between(0, 2147483647)", "minimum": 0, "maximum": 2147483647 }, { "type": "null" } ], "description": "TikTok only: which video frame to use as the cover, in milliseconds from the start." }, "photoCoverIndex": { "anyOf": [ { "type": "number", "description": "a number between 0 and 34", "title": "between(0, 34)", "minimum": 0, "maximum": 34 }, { "type": "null" } ], "description": "TikTok only: zero-based index of the photo to use as the cover of a photo post." }, "autoAddMusic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: let TikTok add recommended music to a photo post (the creator can change the track later). A feature toggle, separate from the music rights confirmation." }, "musicUsageRightsConfirmed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: confirms the publisher holds usage rights for any music in the post. Never assumed; set it explicitly." }, "brandedContent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: discloses the post as paid branded content." }, "brandOrganic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: discloses the post as organic brand content (promoting your own business)." }, "isAigc": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: discloses AI-generated video content." }, "linkUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Facebook only: link to attach to a Page text post." }, "replyControl": { "anyOf": [ { "type": "string", "enum": [ "everyone", "accounts_you_follow", "mentioned_only", "parent_post_author_only", "followers_only" ] }, { "type": "null" } ], "description": "Threads only: who can reply to the root post. null uses the account default." }, "topicTag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Threads only: topic tag attached to the post." }, "quotePostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Threads only: id of an existing Threads post to quote." }, "crossReshareToInstagram": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Threads only: also reshare the published post to Instagram." }, "boardId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pinterest only: id of the public board this Pin is saved to. Defaults to the board captured when the account was connected." }, "pinTitle": { "anyOf": [ { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "maxLength": 100 }, { "type": "null" } ], "description": "Pinterest only: Pin title, max 100 characters. Falls back to the first line of the post text." }, "pinDescription": { "anyOf": [ { "type": "string", "description": "a string at most 800 character(s) long", "title": "maxLength(800)", "maxLength": 800 }, { "type": "null" } ], "description": "Pinterest only: Pin description, max 800 characters. Falls back to the post text." }, "destinationLink": { "anyOf": [ { "type": "string", "description": "a string at most 2048 character(s) long", "title": "maxLength(2048)", "maxLength": 2048 }, { "type": "null" } ], "description": "Pinterest only: outbound link the Pin drives traffic to, max 2048 characters. Never shortened." }, "altText": { "anyOf": [ { "type": "string", "description": "a string at most 500 character(s) long", "title": "maxLength(500)", "maxLength": 500 }, { "type": "null" } ], "description": "Pinterest only: alt text for accessibility, max 500 characters." }, "coverImageAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pinterest only: media-library asset id used as the video Pin cover. When absent, Pinterest extracts the first frame." }, "aiDisclosure": { "anyOf": [ { "type": "string", "enum": [ "ai_modified", "synthetic_performer" ] }, { "type": "null" } ], "description": "Pinterest only: manual AI disclosure for uploaded media. Octospark-generated media is declared automatically from provenance." } }, "additionalProperties": false, "description": "Provider-specific publish settings. Each field applies to one provider (named in its description) and is ignored by accounts on other providers, so a single object can carry settings for every account the post targets. Unknown keys are rejected.", "examples": [ { "replySettings": "following" } ] }, "platformSettingsBySocialAccountId": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "type": "object", "required": [], "properties": { "replySettings": { "anyOf": [ { "type": "string", "enum": [ "following", "mentionedUsers", "subscribers", "verified" ] }, { "type": "null" } ], "description": "X only: who can reply to the published post (following, mentionedUsers, subscribers, or verified). null lets everyone reply." }, "quoteTweetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "X only: id of an existing X post to quote under the new post." }, "visibility": { "anyOf": [ { "type": "string", "enum": [ "PUBLIC", "CONNECTIONS" ] }, { "type": "null" } ], "description": "LinkedIn only: post visibility, PUBLIC or CONNECTIONS. null publishes as PUBLIC." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "LinkedIn, YouTube, and TikTok: title for the published media. Falls back to the first line of the post text where the platform needs one." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube only: video description; falls back to the post text." }, "privacyStatus": { "anyOf": [ { "type": "string", "enum": [ "private", "unlisted", "public" ] }, { "type": "null" } ], "description": "YouTube only: video privacy (private, unlisted, or public). null uploads as private." }, "selfDeclaredMadeForKids": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "YouTube only: marks the video as made for kids (the COPPA self-declaration)." }, "containsSyntheticMedia": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "YouTube only: discloses that the video contains AI-generated or synthetic media." }, "communityGuidelinesConfirmed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "YouTube only: confirms the publisher certifies the upload complies with YouTube Community Guidelines." }, "categoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube only: numeric video category id for the upload." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "YouTube only: tags attached to the uploaded video." }, "thumbnailAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YouTube only: media-library asset id to set as the video thumbnail once the upload succeeds." }, "privacyLevel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TikTok only: privacy level from the account's creator info; valid values vary per account." }, "contentPostingMethod": { "anyOf": [ { "type": "string", "enum": [ "DIRECT_POST", "UPLOAD" ] }, { "type": "null" } ], "description": "TikTok only: DIRECT_POST publishes immediately, UPLOAD sends the post to the creator inbox. null uses DIRECT_POST." }, "mediaTransferMode": { "anyOf": [ { "type": "string", "enum": [ "FILE_UPLOAD", "PULL_FROM_URL" ] }, { "type": "null" } ], "description": "TikTok only: how video bytes reach TikTok (FILE_UPLOAD or PULL_FROM_URL; pull requires a verified HTTPS media URL). Photo posts always pull from URL. null uses FILE_UPLOAD." }, "disableDuet": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: disables duets on the published video." }, "disableComment": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: disables comments on the published post." }, "disableStitch": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: disables stitches on the published video." }, "videoCoverTimestampMs": { "anyOf": [ { "type": "number", "description": "a number between 0 and 2147483647", "title": "between(0, 2147483647)", "minimum": 0, "maximum": 2147483647 }, { "type": "null" } ], "description": "TikTok only: which video frame to use as the cover, in milliseconds from the start." }, "photoCoverIndex": { "anyOf": [ { "type": "number", "description": "a number between 0 and 34", "title": "between(0, 34)", "minimum": 0, "maximum": 34 }, { "type": "null" } ], "description": "TikTok only: zero-based index of the photo to use as the cover of a photo post." }, "autoAddMusic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: let TikTok add recommended music to a photo post (the creator can change the track later). A feature toggle, separate from the music rights confirmation." }, "musicUsageRightsConfirmed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: confirms the publisher holds usage rights for any music in the post. Never assumed; set it explicitly." }, "brandedContent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: discloses the post as paid branded content." }, "brandOrganic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: discloses the post as organic brand content (promoting your own business)." }, "isAigc": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TikTok only: discloses AI-generated video content." }, "linkUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Facebook only: link to attach to a Page text post." }, "replyControl": { "anyOf": [ { "type": "string", "enum": [ "everyone", "accounts_you_follow", "mentioned_only", "parent_post_author_only", "followers_only" ] }, { "type": "null" } ], "description": "Threads only: who can reply to the root post. null uses the account default." }, "topicTag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Threads only: topic tag attached to the post." }, "quotePostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Threads only: id of an existing Threads post to quote." }, "crossReshareToInstagram": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Threads only: also reshare the published post to Instagram." }, "boardId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pinterest only: id of the public board this Pin is saved to. Defaults to the board captured when the account was connected." }, "pinTitle": { "anyOf": [ { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "maxLength": 100 }, { "type": "null" } ], "description": "Pinterest only: Pin title, max 100 characters. Falls back to the first line of the post text." }, "pinDescription": { "anyOf": [ { "type": "string", "description": "a string at most 800 character(s) long", "title": "maxLength(800)", "maxLength": 800 }, { "type": "null" } ], "description": "Pinterest only: Pin description, max 800 characters. Falls back to the post text." }, "destinationLink": { "anyOf": [ { "type": "string", "description": "a string at most 2048 character(s) long", "title": "maxLength(2048)", "maxLength": 2048 }, { "type": "null" } ], "description": "Pinterest only: outbound link the Pin drives traffic to, max 2048 characters. Never shortened." }, "altText": { "anyOf": [ { "type": "string", "description": "a string at most 500 character(s) long", "title": "maxLength(500)", "maxLength": 500 }, { "type": "null" } ], "description": "Pinterest only: alt text for accessibility, max 500 characters." }, "coverImageAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pinterest only: media-library asset id used as the video Pin cover. When absent, Pinterest extracts the first frame." }, "aiDisclosure": { "anyOf": [ { "type": "string", "enum": [ "ai_modified", "synthetic_performer" ] }, { "type": "null" } ], "description": "Pinterest only: manual AI disclosure for uploaded media. Octospark-generated media is declared automatically from provenance." } }, "additionalProperties": false, "description": "Provider-specific publish settings. Each field applies to one provider (named in its description) and is ignored by accounts on other providers, so a single object can carry settings for every account the post targets. Unknown keys are rejected.", "examples": [ { "replySettings": "following" } ] }, "description": "Per-account overrides of the shared platform settings, keyed by social account UUID; values merge over platformSettings for that account." }, "overrideApproval": { "type": "boolean", "description": "When the workspace postApprovalMode is required, bypasses the client-approval gate for this call. Requires team admin permission (manage-level); the override is audited as an internal approval decision.", "examples": [ true ] }, "textBySocialAccountId": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "type": "string" }, "description": "Per-account body-text overrides, keyed by social account UUID. An entry replaces the post's shared text for that account's leg only; accounts without an entry publish the shared text. Text-only: media attachments and platform settings are unaffected, and thread posts reject overrides. Entries must be non-blank." }, "firstComment": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false, "description": "Comment to post on the published post immediately after it goes live." }, "engagementCommentTrigger": { "type": "object", "required": [ "likeThreshold", "windowHours", "comment" ], "properties": { "likeThreshold": { "$ref": "#/components/schemas/Int", "description": "a number greater than or equal to 1", "title": "greaterThanOrEqualTo(1)", "minimum": 1 }, "windowHours": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 720", "title": "between(1, 720)", "minimum": 1, "maximum": 720 }, "comment": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Comment to post once the published post reaches likeThreshold likes within windowHours (1 to 720 hours)." }, "repostAfter": { "type": "object", "required": [ "offsetDays", "mode" ], "properties": { "offsetDays": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 30", "title": "between(1, 30)", "minimum": 1, "maximum": 30 }, "mode": { "type": "string", "enum": [ "retweet", "quote" ] }, "text": { "type": "string" } }, "additionalProperties": false, "description": "Repost the published post offsetDays (1 to 30) after publish, either as a plain retweet or a quote (text required for quote mode)." }, "recurrenceIntervalDays": { "$ref": "#/components/schemas/Int", "description": "Republish the post every N days (1 to 365) until recurrenceEndsAt.", "title": "between(1, 365)", "examples": [ 7 ], "minimum": 1, "maximum": 365 }, "recurrenceEndsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp after which the recurrence stops; null means no end date.", "examples": [ "2026-09-01T00:00:00Z" ] } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.postNow({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.post_now(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark posts publish \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/post-now\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/post-now';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Post now", "x-displayName": "Post now" } }, "/v1/teams/{teamId}/posts/{postId}/move-to-draft": { "post": { "tags": [ "Posts" ], "operationId": "social.movePostToDraft", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "postType", "artifactKind", "title", "status", "workflowStatusId", "text", "assetIds", "media", "assetTags", "userTags", "assignees", "contentPayloadId", "latestScheduledPost", "scheduledDestinationAccountIds", "draftDestinationAccountIds", "saveDestination", "saveMessage", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "UUID of the post.", "examples": [ "3c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "postType": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel" ], "description": "Content format of a post: text_post (text only), text_image, text_video, or carousel (2+ photos).", "examples": [ "text_post", "text_image" ] }, "artifactKind": { "anyOf": [ { "type": "string", "enum": [ "slideshow", "image_meme", "green_screen_meme" ] }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "idea", "proposed_render", "draft", "in_review", "approved", "rejected", "archived", "deleted" ], "description": "Editorial status of a post: idea, proposed_render, draft, approved, rejected, archived, or deleted.", "examples": [ "draft", "approved" ] }, "workflowStatusId": { "type": "string", "description": "Workspace-defined content workflow status currently assigned to the post.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "text": { "type": "string" }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "media": { "type": "array", "items": { "type": "object", "required": [ "assetId", "mimeType", "displayName", "thumbnailPath" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "displayName": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Display metadata (mime type, name, thumbnail path) for the post's media, in the same order as assetIds. Empty for text-only posts." }, "assetTags": { "type": "array", "items": { "type": "string" }, "description": "Deduped, sorted union of the post's non-deleted assets' AI tags; empty for text-only posts.", "examples": [ [ "launch", "product" ] ] }, "userTags": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "colour" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" } }, "additionalProperties": false }, "description": "User/agent-assigned registry tags (id, name, colour) on the post; distinct from AI-derived assetTags. Empty when no tags are assigned." }, "assignees": { "type": "array", "items": { "type": "object", "required": [ "userId", "name", "email" ], "properties": { "userId": { "$ref": "#/components/schemas/UUID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Team members assigned to the post (userId plus display name/email), in assignment order. Empty when unassigned. Set via the setPostAssignees endpoint." }, "postInput": { "anyOf": [ { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "posts" ], "properties": { "kind": { "type": "string", "enum": [ "thread" ] }, "posts": { "type": "array", "items": { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enum": [ "atomic" ] }, "text": { "type": "string" }, "attachments": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "kind", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "media" ] }, "asset": { "type": "object", "required": [ "assetId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "mimeType": { "type": "string" }, "byteSize": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "durationSeconds": { "type": "number" }, "thumbnailUrl": { "type": "string" }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif", "document" ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "url" ], "properties": { "kind": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ] } }, "videoVariant": { "type": "string", "enum": [ "green_screen_meme", "video_slideshow" ], "description": "Rendering variant for text_video posts: green_screen_meme or video_slideshow.", "examples": [ "green_screen_meme" ] } }, "additionalProperties": false }, "description": "an array of at least 2 item(s)", "title": "minItems(2)", "minItems": 2 } }, "additionalProperties": false } ] }, "postPublishActions": { "type": "object", "required": [], "properties": { "firstComment": { "anyOf": [ { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false }, { "type": "null" } ] }, "engagementCommentTrigger": { "anyOf": [ { "type": "object", "required": [ "likeThreshold", "windowHours", "comment" ], "properties": { "likeThreshold": { "$ref": "#/components/schemas/Int", "description": "a number greater than or equal to 1", "title": "greaterThanOrEqualTo(1)", "minimum": 1 }, "windowHours": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 720", "title": "between(1, 720)", "minimum": 1, "maximum": 720 }, "comment": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "null" } ] }, "repostAfter": { "anyOf": [ { "type": "object", "required": [ "offsetDays", "mode" ], "properties": { "offsetDays": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 30", "title": "between(1, 30)", "minimum": 1, "maximum": 30 }, "mode": { "type": "string", "enum": [ "retweet", "quote" ] }, "text": { "type": "string" } }, "additionalProperties": false, "description": "Repost the published post offsetDays (1 to 30) after publish, either as a plain retweet or a quote (text required for quote mode)." }, { "type": "null" } ] }, "recurrenceIntervalDays": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 365", "title": "between(1, 365)", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "recurrenceEndsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "contentPayloadId": { "$ref": "#/components/schemas/UUID" }, "latestScheduledPost": { "anyOf": [ { "type": "object", "required": [ "id", "teamId", "contentItemId", "socialAccountId", "provider", "status", "scheduledAt", "timezone", "platformPostId", "platformSettings", "publishResults", "providerPublishState", "errorCode", "errorMessage", "errorCategory", "workflowId", "workflowRunId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "UUID of this scheduled post (one per target social account).", "examples": [ "7f3a2b10-9c4d-4e5f-8a6b-1c2d3e4f5a6b" ], "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "socialAccountId": { "$ref": "#/components/schemas/UUID" }, "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "publishing", "published", "failed", "cancelled" ], "description": "Lifecycle status of a scheduled post: draft, scheduled, publishing, published, failed, or cancelled.", "examples": [ "scheduled", "published" ] }, "scheduledAt": { "type": "string", "description": "ISO 8601 timestamp the post is or was due to publish.", "examples": [ "2026-06-15T09:00:00.000Z" ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone name the schedule was chosen in, or null when not recorded.", "examples": [ "Europe/London" ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformSettings": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "publishResults": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "providerPublishState": { "type": "object", "required": [ "provider", "status", "requiresPolling", "publishId", "platformPostId", "providerStatus", "pollingReason", "uploadProgress", "failureCode", "failureCategory" ], "properties": { "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "status": { "type": "string", "enum": [ "not_started", "pending", "published", "failed", "unknown" ] }, "requiresPolling": { "type": "boolean" }, "publishId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pollingReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "uploadProgress": { "anyOf": [ { "type": "object", "required": [ "nextByteStart", "uploadSize" ], "properties": { "nextByteStart": { "type": "number" }, "uploadSize": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] } }, "additionalProperties": false }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCategory": { "anyOf": [ { "type": "string", "enum": [ "rate_limited", "transient", "auth", "validation", "permanent", "requires_action" ] }, { "type": "null" } ] }, "workflowId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "scheduledDestinationAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "draftDestinationAccountIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "UUIDs of the social accounts selected for this draft. Empty clears the saved selection and duplicates are rejected.", "examples": [ [ "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" ] ] }, "saveDestination": { "type": "string", "enum": [ "queue", "drafts" ] }, "saveMessage": { "type": "string", "enum": [ "Saved to Queue", "Saved to Drafts" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Cancel a post's schedule and any pending publish actions, returning it to draft status. Use this to stop an upcoming publish without deleting the post; you can then edit with updatePost and reschedule with schedulePost.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.movePostToDraft({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.move_post_to_draft(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark social move-post-to-draft \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/move-to-draft\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/move-to-draft';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.post(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Move post to draft", "x-displayName": "Move post to draft" } }, "/v1/teams/{teamId}/posts/facets/enrichment": { "get": { "tags": [ "Posts" ], "operationId": "social.listPostEnrichmentFacets", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "fields", "in": "query", "schema": { "type": "string", "description": "Comma-separated subset of enrichment field keys to return facets for (e.g. tags, category); omit for all fields.", "examples": [ "tags,category" ] }, "required": false, "description": "Comma-separated subset of enrichment field keys to return facets for (e.g. tags, category); omit for all fields." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "field", "values" ], "properties": { "field": { "type": "string", "enum": [ "tags", "category", "purpose", "emotion", "mediaType", "enrichmentStatus" ] }, "values": { "type": "array", "items": { "type": "object", "required": [ "value", "postCount" ], "properties": { "value": { "type": "string" }, "postCount": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the enrichment facet values present across a team's posts (AI-derived attributes such as topics or categories) with their counts. Use the returned values as enrichment filters on listPosts to narrow a post search.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.listPostEnrichmentFacets({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.list_post_enrichment_facets(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark social list-post-enrichment-facets \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/facets/enrichment\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/facets/enrichment';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List post enrichment facets", "x-displayName": "List post enrichment facets" } }, "/v1/teams/{teamId}/scheduling-slots": { "get": { "tags": [ "Scheduling slots" ], "operationId": "schedulingSlots.listSchedulingSlots", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "source", "timezone", "slots" ], "properties": { "source": { "type": "string", "enum": [ "custom", "default" ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slots": { "type": "array", "items": { "type": "object", "required": [ "id", "hour", "minute", "label", "daysOfWeek" ], "properties": { "id": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "hour": { "$ref": "#/components/schemas/Int" }, "minute": { "$ref": "#/components/schemas/Int" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "daysOfWeek": { "type": "array", "items": { "$ref": "#/components/schemas/Int" } } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List a team's effective scheduling slots: the custom rows when any exist (source \"custom\"), otherwise the implicit morning/afternoon/evening defaults (source \"default\"), plus the team timezone. Slots are sorted by (hour, minute). Use these as the posting grid the composer/calendar render and that useNextSlot resolves against.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.schedulingSlots.listSchedulingSlots({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.scheduling_slots.list_scheduling_slots(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark scheduling-slots list-scheduling-slots \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/scheduling-slots\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/scheduling-slots';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List scheduling slots", "x-displayName": "List scheduling slots" }, "post": { "tags": [ "Scheduling slots" ], "operationId": "schedulingSlots.createSchedulingSlot", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "hour", "minute", "label", "daysOfWeek", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "hour": { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 23", "title": "between(0, 23)", "minimum": 0, "maximum": 23 }, "minute": { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 59", "title": "between(0, 59)", "minimum": 0, "maximum": 59 }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "daysOfWeek": { "type": "array", "items": { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 6", "title": "between(0, 6)", "minimum": 0, "maximum": 6 }, "description": "an array of at least 1 item(s)", "title": "minItems(1)", "minItems": 1 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create a custom scheduling slot (hour 0-23, minute 0-59, optional label, optional daysOfWeek where 0 = Sunday and the default is all 7 days). Adding the first custom slot switches the team from implicit defaults to its custom grid. A duplicate (hour, minute) is rejected 409; exceeding 350 weekly occurrences across all rows is rejected 409 with no row written.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "hour", "minute" ], "properties": { "hour": { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 23", "title": "between(0, 23)", "minimum": 0, "maximum": 23 }, "minute": { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 59", "title": "between(0, 59)", "minimum": 0, "maximum": 59 }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional human-friendly name for this slot (for example \"Morning\" or \"Lunch\"), shown in the composer and calendar. Omit it or send null to leave the slot unlabelled." }, "daysOfWeek": { "type": "array", "items": { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 6", "title": "between(0, 6)", "minimum": 0, "maximum": 6 }, "description": "Days of the week this slot fires on, as integers where 0 is Sunday through 6 is Saturday. Omit to default to all seven days.", "title": "minItems(1)", "minItems": 1 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.schedulingSlots.createSchedulingSlot({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.scheduling_slots.create_scheduling_slot(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark scheduling-slots create-scheduling-slot \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/scheduling-slots\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/scheduling-slots';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create scheduling slot", "x-displayName": "Create scheduling slot" } }, "/v1/teams/{teamId}/scheduling-slots/{slotId}": { "patch": { "tags": [ "Scheduling slots" ], "operationId": "schedulingSlots.updateSchedulingSlot", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "slotId", "in": "path", "schema": { "type": "string", "description": "Scheduling slot id (UUID) from the team scheduling-slot grid, as returned by the list/create scheduling-slots endpoints." }, "required": true, "description": "Scheduling slot id (UUID) from the team scheduling-slot grid, as returned by the list/create scheduling-slots endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "hour", "minute", "label", "daysOfWeek", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "hour": { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 23", "title": "between(0, 23)", "minimum": 0, "maximum": 23 }, "minute": { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 59", "title": "between(0, 59)", "minimum": 0, "maximum": 59 }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "daysOfWeek": { "type": "array", "items": { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 6", "title": "between(0, 6)", "minimum": 0, "maximum": 6 }, "description": "an array of at least 1 item(s)", "title": "minItems(1)", "minItems": 1 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Partially update a custom scheduling slot (any of hour, minute, label, daysOfWeek). A change that collides with another slot's (hour, minute) is rejected 409; one that would push the team past 350 weekly occurrences is rejected 409 with no change written.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "hour": { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 23", "title": "between(0, 23)", "minimum": 0, "maximum": 23 }, "minute": { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 59", "title": "between(0, 59)", "minimum": 0, "maximum": 59 }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional human-friendly name for this slot (for example \"Morning\" or \"Lunch\"), shown in the composer and calendar. Omit it or send null to leave the slot unlabelled." }, "daysOfWeek": { "type": "array", "items": { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 6", "title": "between(0, 6)", "minimum": 0, "maximum": 6 }, "description": "Days of the week this slot fires on, as integers where 0 is Sunday through 6 is Saturday. Omit to default to all seven days.", "title": "minItems(1)", "minItems": 1 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.schedulingSlots.updateSchedulingSlot({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n slotId: process.env.OCTOSPARK_SLOT_ID ?? \"slotId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.scheduling_slots.update_scheduling_slot(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n slotId=os.environ.get(\"OCTOSPARK_SLOT_ID\", \"slotId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark scheduling-slots update-scheduling-slot \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"slotId\":\"slotId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let slot_id = env::var(\"OCTOSPARK_SLOT_ID\").unwrap_or_else(|_| \"slotId\".to_string());\n let url = format!(\"{}/v1/teams/{}/scheduling-slots/{}\", base_url.trim_end_matches('/'), team_id, slot_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final slotId = Platform.environment['OCTOSPARK_SLOT_ID'] ?? 'slotId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/scheduling-slots/$slotId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Update scheduling slot", "x-displayName": "Update scheduling slot" }, "delete": { "tags": [ "Scheduling slots" ], "operationId": "schedulingSlots.deleteSchedulingSlot", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "slotId", "in": "path", "schema": { "type": "string", "description": "Scheduling slot id (UUID) from the team scheduling-slot grid, as returned by the list/create scheduling-slots endpoints." }, "required": true, "description": "Scheduling slot id (UUID) from the team scheduling-slot grid, as returned by the list/create scheduling-slots endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Delete a custom scheduling slot. Deleting the last custom row reverts the team to the implicit morning/afternoon/evening defaults. Existing scheduled posts are unaffected.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.schedulingSlots.deleteSchedulingSlot({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n slotId: process.env.OCTOSPARK_SLOT_ID ?? \"slotId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.scheduling_slots.delete_scheduling_slot(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n slotId=os.environ.get(\"OCTOSPARK_SLOT_ID\", \"slotId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark scheduling-slots delete-scheduling-slot \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"slotId\":\"slotId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let slot_id = env::var(\"OCTOSPARK_SLOT_ID\").unwrap_or_else(|_| \"slotId\".to_string());\n let url = format!(\"{}/v1/teams/{}/scheduling-slots/{}\", base_url.trim_end_matches('/'), team_id, slot_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final slotId = Platform.environment['OCTOSPARK_SLOT_ID'] ?? 'slotId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/scheduling-slots/$slotId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete scheduling slot", "x-displayName": "Delete scheduling slot" } }, "/v1/teams/{teamId}/scheduling-slots/next": { "get": { "tags": [ "Scheduling slots" ], "operationId": "schedulingSlots.getNextSchedulingSlots", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "socialAccountId", "in": "query", "schema": { "type": "string", "description": "Connected social account id (UUID). When provided, the preview is occupancy-aware for that account; omit for a purely time-based preview." }, "required": false, "description": "Connected social account id (UUID). When provided, the preview is occupancy-aware for that account; omit for a purely time-based preview." }, { "name": "count", "in": "query", "schema": { "type": "string", "description": "How many upcoming slot instants to return, 1-20 (default 1). Values outside the range are clamped." }, "required": false, "description": "How many upcoming slot instants to return, 1-20 (default 1). Values outside the range are clamped." }, { "name": "timezone", "in": "query", "schema": { "type": "string", "description": "IANA timezone override used only when the team has no stored timezone; validated against the runtime's supported list (400 on an unsupported name).", "examples": [ "Europe/London" ] }, "required": false, "description": "IANA timezone override used only when the team has no stored timezone; validated against the runtime's supported list (400 on an unsupported name)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "slots" ], "properties": { "slots": { "type": "array", "items": { "type": "object", "required": [ "startsAt", "hour", "minute", "label" ], "properties": { "startsAt": { "type": "string" }, "hour": { "$ref": "#/components/schemas/Int" }, "minute": { "$ref": "#/components/schemas/Int" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Preview the next candidate scheduling-slot instants without scheduling anything. Occupancy-aware when socialAccountId is supplied (skips slot windows already taken by that account's active posts), purely time-based otherwise. count defaults to 1 (max 20). Read-only: never spends credits and never writes a post.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.schedulingSlots.getNextSchedulingSlots({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.scheduling_slots.get_next_scheduling_slots(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark scheduling-slots get-next-scheduling-slots \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/scheduling-slots/next\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/scheduling-slots/next';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Next scheduling slots", "x-displayName": "Next scheduling slots" } }, "/v1/teams/{teamId}/analytics/aggregates": { "get": { "tags": [ "Analytics" ], "operationId": "social.getAnalyticsAggregates", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "from", "in": "query", "schema": { "type": "string", "description": "Start of the reporting window, ISO 8601 timestamp (inclusive).", "examples": [ "2026-05-01T00:00:00.000Z" ] }, "required": true, "description": "Start of the reporting window, ISO 8601 timestamp (inclusive)." }, { "name": "to", "in": "query", "schema": { "type": "string", "description": "End of the reporting window, ISO 8601 timestamp (inclusive).", "examples": [ "2026-05-31T23:59:59.000Z" ] }, "required": true, "description": "End of the reporting window, ISO 8601 timestamp (inclusive)." }, { "name": "platform", "in": "query", "schema": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Restrict aggregates to one provider; omit for all connected providers.", "examples": [ "x" ] }, "required": false, "description": "Restrict aggregates to one provider; omit for all connected providers." }, { "name": "postType", "in": "query", "schema": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel", "thread", "" ], "description": "Restrict aggregates to one content format; empty or omitted includes all formats." }, "required": false, "description": "Restrict aggregates to one content format; empty or omitted includes all formats." }, { "name": "tagIds", "in": "query", "schema": { "type": "string", "description": "CSV of user-tag UUIDs; restricts aggregates to posts assigned ANY of these tags." }, "required": false, "description": "CSV of user-tag UUIDs; restricts aggregates to posts assigned ANY of these tags." }, { "name": "filter[postType]", "in": "query", "schema": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel", "thread", "" ], "description": "Alias of postType using the filter[...] convention." }, "required": false, "description": "Alias of postType using the filter[...] convention." }, { "name": "filter[tagIds]", "in": "query", "schema": { "type": "string", "description": "Alias of tagIds using the filter[...] convention; CSV of user-tag UUIDs." }, "required": false, "description": "Alias of tagIds using the filter[...] convention; CSV of user-tag UUIDs." }, { "name": "filter[tags]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI tags; matches posts whose assets carry any of the listed tags (OR).", "examples": [ "launch,product" ] }, "required": false, "description": "Comma-separated AI tags; matches posts whose assets carry any of the listed tags (OR)." }, { "name": "filter[category]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI content categories; matches posts in any of the listed categories (OR).", "examples": [ "education" ] }, "required": false, "description": "Comma-separated AI content categories; matches posts in any of the listed categories (OR)." }, { "name": "filter[purpose]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI purposes; matches posts whose assets carry any of the listed purposes (OR).", "examples": [ "promotion" ] }, "required": false, "description": "Comma-separated AI purposes; matches posts whose assets carry any of the listed purposes (OR)." }, { "name": "filter[emotion]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI emotions; matches posts tagged with any of the listed emotions (OR).", "examples": [ "joy" ] }, "required": false, "description": "Comma-separated AI emotions; matches posts tagged with any of the listed emotions (OR)." }, { "name": "filter[mediaType]", "in": "query", "schema": { "type": "string", "description": "Comma-separated media types; each value one of: image, video, audio, gif, document.", "examples": [ "image,video" ] }, "required": false, "description": "Comma-separated media types; each value one of: image, video, audio, gif, document." }, { "name": "filter[enrichmentStatus]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI enrichment statuses; each value one of: pending, processing, completed, failed.", "examples": [ "completed" ] }, "required": false, "description": "Comma-separated AI enrichment statuses; each value one of: pending, processing, completed, failed." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "period", "totals", "byPlatform", "byWeek", "byDay" ], "properties": { "period": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "additionalProperties": false }, "totals": { "type": "object", "required": [ "likeCount", "commentCount", "shareCount", "saveCount", "impressionCount", "reachCount", "postCount", "linkClickCount", "averageEngagementRate" ], "properties": { "likeCount": { "type": "number" }, "commentCount": { "type": "number" }, "shareCount": { "type": "number" }, "saveCount": { "type": "number" }, "impressionCount": { "type": "number" }, "reachCount": { "type": "number" }, "postCount": { "type": "number" }, "linkClickCount": { "type": "number" }, "averageEngagementRate": { "type": "number" } }, "additionalProperties": false }, "byPlatform": { "type": "array", "items": { "type": "object", "required": [ "platform", "likeCount", "commentCount", "shareCount", "saveCount", "impressionCount", "reachCount", "postCount", "linkClickCount", "averageEngagementRate" ], "properties": { "platform": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "likeCount": { "type": "number" }, "commentCount": { "type": "number" }, "shareCount": { "type": "number" }, "saveCount": { "type": "number" }, "impressionCount": { "type": "number" }, "reachCount": { "type": "number" }, "postCount": { "type": "number" }, "linkClickCount": { "type": "number" }, "averageEngagementRate": { "type": "number" } }, "additionalProperties": false } }, "byWeek": { "type": "array", "items": { "type": "object", "required": [ "weekStart", "platform", "likeCount", "commentCount", "shareCount", "saveCount", "impressionCount", "postCount", "linkClickCount", "averageEngagementRate" ], "properties": { "weekStart": { "type": "string" }, "platform": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "likeCount": { "type": "number" }, "commentCount": { "type": "number" }, "shareCount": { "type": "number" }, "saveCount": { "type": "number" }, "impressionCount": { "type": "number" }, "postCount": { "type": "number" }, "linkClickCount": { "type": "number" }, "averageEngagementRate": { "type": "number" } }, "additionalProperties": false } }, "byDay": { "type": "array", "items": { "type": "object", "required": [ "date", "likeCount", "commentCount", "shareCount", "saveCount", "impressionCount", "postCount", "linkClickCount", "averageEngagementRate" ], "properties": { "date": { "type": "string" }, "likeCount": { "type": "number" }, "commentCount": { "type": "number" }, "shareCount": { "type": "number" }, "saveCount": { "type": "number" }, "impressionCount": { "type": "number" }, "postCount": { "type": "number" }, "linkClickCount": { "type": "number" }, "averageEngagementRate": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Return team-wide analytics aggregated across posts and accounts for a time window, read from stored metrics. Free: no credits spent and no live provider calls. Use listAccountAnalytics for per-account breakdowns or listPostPerformance for per-post metrics.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.getAnalyticsAggregates({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {\n \"from\": process.env.OCTOSPARK_FROM ?? \"from\",\n \"to\": process.env.OCTOSPARK_TO ?? \"to\",\n },\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.get_analytics_aggregates(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n query={\n \"from\": os.environ.get(\"OCTOSPARK_FROM\", \"from\"),\n \"to\": os.environ.get(\"OCTOSPARK_TO\", \"to\"),\n }\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark analytics summary \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"query\":{\"from\":\"from\",\"to\":\"to\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let from = env::var(\"OCTOSPARK_FROM\").unwrap_or_else(|_| \"from\".to_string());\n let to = env::var(\"OCTOSPARK_TO\").unwrap_or_else(|_| \"to\".to_string());\n let url = format!(\"{}/v1/teams/{}/analytics/aggregates\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let query = [(\"from\", from.as_str()), (\"to\", to.as_str())];\n request = request.query(&query);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final from = Platform.environment['OCTOSPARK_FROM'] ?? 'from';\n final to = Platform.environment['OCTOSPARK_TO'] ?? 'to';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/analytics/aggregates';\n final uri = Uri.parse(url).replace(queryParameters: {\n 'from': from,\n 'to': to,\n });\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Analytics aggregates", "x-displayName": "Analytics aggregates" } }, "/v1/teams/{teamId}/analytics/accounts": { "get": { "tags": [ "Analytics" ], "operationId": "social.listAccountAnalytics", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "from", "in": "query", "schema": { "type": "string", "description": "Start of the follower-history window, ISO 8601 timestamp or YYYY-MM-DD (inclusive). Provide with `to` to include a per-account daily `series`.", "examples": [ "2026-05-01" ] }, "required": false, "description": "Start of the follower-history window, ISO 8601 timestamp or YYYY-MM-DD (inclusive). Provide with `to` to include a per-account daily `series`." }, { "name": "to", "in": "query", "schema": { "type": "string", "description": "End of the follower-history window, ISO 8601 timestamp or YYYY-MM-DD (inclusive).", "examples": [ "2026-05-31" ] }, "required": false, "description": "End of the follower-history window, ISO 8601 timestamp or YYYY-MM-DD (inclusive)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "socialAccountId", "provider", "displayName", "profileHandle", "status", "capabilityStatus", "uiEnabled" ], "properties": { "socialAccountId": { "$ref": "#/components/schemas/UUID" }, "provider": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "displayName": { "type": "string" }, "profileHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "available", "disabled", "failed", "unsupported" ] }, "capabilityStatus": { "type": "string" }, "uiEnabled": { "type": "boolean" }, "collectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metrics": { "anyOf": [ { "type": "object", "required": [ "followerCount", "followingCount", "subscriberCount", "postCount", "viewCount", "likeCount", "commentCount", "shareCount", "saveCount", "reachCount", "impressionCount", "profileViewCount" ], "properties": { "followerCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "followingCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "subscriberCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "postCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "viewCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "likeCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "commentCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shareCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "saveCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "reachCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "impressionCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "profileViewCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "series": { "type": "array", "items": { "type": "object", "required": [ "snapshotDate", "metrics" ], "properties": { "snapshotDate": { "type": "string", "description": "UTC calendar date of the snapshot (YYYY-MM-DD).", "examples": [ "2026-05-01" ] }, "metrics": { "type": "object", "required": [ "followerCount", "followingCount", "subscriberCount", "postCount", "viewCount", "likeCount", "commentCount", "shareCount", "saveCount", "reachCount", "impressionCount", "profileViewCount" ], "properties": { "followerCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "followingCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "subscriberCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "postCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "viewCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "likeCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "commentCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shareCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "saveCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "reachCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "impressionCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "profileViewCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Read account-level analytics (followers, following, posts, likes) for each of the team's connected social accounts, served from the stored daily snapshots. Free: no credits spent and no live provider calls. Returns the latest snapshot per account by default; pass BOTH `from` and `to` to also include a per-account daily `series` (bounded server-side) for follower-growth charts and previous-period deltas. Use getAnalyticsAggregates for the free, stored team-wide post rollup.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.listAccountAnalytics({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.list_account_analytics(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark analytics posts \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"query\":{\"from\":\"from\",\"to\":\"to\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/analytics/accounts\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/analytics/accounts';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List account analytics", "x-displayName": "List account analytics" } }, "/v1/teams/{teamId}/analytics/by-dimension": { "get": { "tags": [ "Analytics" ], "operationId": "social.getAnalyticsByDimension", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "from", "in": "query", "schema": { "type": "string", "description": "Start of the reporting window, ISO 8601 timestamp (inclusive).", "examples": [ "2026-05-01T00:00:00.000Z" ] }, "required": true, "description": "Start of the reporting window, ISO 8601 timestamp (inclusive)." }, { "name": "to", "in": "query", "schema": { "type": "string", "description": "End of the reporting window, ISO 8601 timestamp (inclusive).", "examples": [ "2026-05-31T23:59:59.000Z" ] }, "required": true, "description": "End of the reporting window, ISO 8601 timestamp (inclusive)." }, { "name": "platform", "in": "query", "schema": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Restrict aggregates to one provider; omit for all connected providers.", "examples": [ "x" ] }, "required": false, "description": "Restrict aggregates to one provider; omit for all connected providers." }, { "name": "postType", "in": "query", "schema": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel", "thread", "" ], "description": "Restrict aggregates to one content format; empty or omitted includes all formats." }, "required": false, "description": "Restrict aggregates to one content format; empty or omitted includes all formats." }, { "name": "tagIds", "in": "query", "schema": { "type": "string", "description": "CSV of user-tag UUIDs; restricts aggregates to posts assigned ANY of these tags." }, "required": false, "description": "CSV of user-tag UUIDs; restricts aggregates to posts assigned ANY of these tags." }, { "name": "filter[postType]", "in": "query", "schema": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel", "thread", "" ], "description": "Alias of postType using the filter[...] convention." }, "required": false, "description": "Alias of postType using the filter[...] convention." }, { "name": "filter[tagIds]", "in": "query", "schema": { "type": "string", "description": "Alias of tagIds using the filter[...] convention; CSV of user-tag UUIDs." }, "required": false, "description": "Alias of tagIds using the filter[...] convention; CSV of user-tag UUIDs." }, { "name": "filter[tags]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI tags; matches posts whose assets carry any of the listed tags (OR).", "examples": [ "launch,product" ] }, "required": false, "description": "Comma-separated AI tags; matches posts whose assets carry any of the listed tags (OR)." }, { "name": "filter[category]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI content categories; matches posts in any of the listed categories (OR).", "examples": [ "education" ] }, "required": false, "description": "Comma-separated AI content categories; matches posts in any of the listed categories (OR)." }, { "name": "filter[purpose]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI purposes; matches posts whose assets carry any of the listed purposes (OR).", "examples": [ "promotion" ] }, "required": false, "description": "Comma-separated AI purposes; matches posts whose assets carry any of the listed purposes (OR)." }, { "name": "filter[emotion]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI emotions; matches posts tagged with any of the listed emotions (OR).", "examples": [ "joy" ] }, "required": false, "description": "Comma-separated AI emotions; matches posts tagged with any of the listed emotions (OR)." }, { "name": "filter[mediaType]", "in": "query", "schema": { "type": "string", "description": "Comma-separated media types; each value one of: image, video, audio, gif, document.", "examples": [ "image,video" ] }, "required": false, "description": "Comma-separated media types; each value one of: image, video, audio, gif, document." }, { "name": "filter[enrichmentStatus]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI enrichment statuses; each value one of: pending, processing, completed, failed.", "examples": [ "completed" ] }, "required": false, "description": "Comma-separated AI enrichment statuses; each value one of: pending, processing, completed, failed." }, { "name": "groupBy", "in": "query", "schema": { "type": "string", "enum": [ "platform", "contentType", "userTag", "mediaType", "category", "emotion", "purpose" ], "description": "Content dimension to group post analytics by: platform, contentType, or userTag count a post once per bucket; asset-derived dimensions (mediaType, category, emotion, purpose) can count a post in multiple buckets.", "examples": [ "platform" ] }, "required": true, "description": "Content dimension to group post analytics by: platform, contentType, or userTag count a post once per bucket; asset-derived dimensions (mediaType, category, emotion, purpose) can count a post in multiple buckets." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "dimension", "value", "postCount", "totals" ], "properties": { "dimension": { "type": "string", "enum": [ "platform", "contentType", "userTag", "mediaType", "category", "emotion", "purpose" ] }, "value": { "type": "string" }, "postCount": { "type": "number" }, "totals": { "type": "object", "required": [ "likeCount", "commentCount", "shareCount", "saveCount", "impressionCount", "reachCount", "postCount", "linkClickCount", "averageEngagementRate" ], "properties": { "likeCount": { "type": "number" }, "commentCount": { "type": "number" }, "shareCount": { "type": "number" }, "saveCount": { "type": "number" }, "impressionCount": { "type": "number" }, "reachCount": { "type": "number" }, "postCount": { "type": "number" }, "linkClickCount": { "type": "number" }, "averageEngagementRate": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false } } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Group the team's stored post analytics by one content dimension (e.g. platform, post type, or a content-profile facet) over a time window. Free: reads stored metrics only, no live provider calls. Use getAnalyticsAggregates for the ungrouped rollup.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.getAnalyticsByDimension({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {\n \"from\": process.env.OCTOSPARK_FROM ?? \"from\",\n \"to\": process.env.OCTOSPARK_TO ?? \"to\",\n \"groupBy\": process.env.OCTOSPARK_GROUP_BY ?? \"groupBy\",\n },\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.get_analytics_by_dimension(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n query={\n \"from\": os.environ.get(\"OCTOSPARK_FROM\", \"from\"),\n \"to\": os.environ.get(\"OCTOSPARK_TO\", \"to\"),\n \"groupBy\": os.environ.get(\"OCTOSPARK_GROUP_BY\", \"groupBy\"),\n }\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark social get-analytics-by-dimension \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"query\":{\"from\":\"from\",\"to\":\"to\",\"groupBy\":\"groupBy\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let from = env::var(\"OCTOSPARK_FROM\").unwrap_or_else(|_| \"from\".to_string());\n let to = env::var(\"OCTOSPARK_TO\").unwrap_or_else(|_| \"to\".to_string());\n let group_by = env::var(\"OCTOSPARK_GROUP_BY\").unwrap_or_else(|_| \"groupBy\".to_string());\n let url = format!(\"{}/v1/teams/{}/analytics/by-dimension\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let query = [(\"from\", from.as_str()), (\"to\", to.as_str()), (\"groupBy\", group_by.as_str())];\n request = request.query(&query);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final from = Platform.environment['OCTOSPARK_FROM'] ?? 'from';\n final to = Platform.environment['OCTOSPARK_TO'] ?? 'to';\n final groupBy = Platform.environment['OCTOSPARK_GROUP_BY'] ?? 'groupBy';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/analytics/by-dimension';\n final uri = Uri.parse(url).replace(queryParameters: {\n 'from': from,\n 'to': to,\n 'groupBy': groupBy,\n });\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Analytics by dimension", "x-displayName": "Analytics by dimension" } }, "/v1/teams/{teamId}/posts/{postId}/performance": { "get": { "tags": [ "Analytics" ], "operationId": "social.getPostPerformance", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "scheduledPostId", "platform", "collectionStatus", "current", "derivedMetrics", "content", "snapshots" ], "properties": { "scheduledPostId": { "$ref": "#/components/schemas/UUID" }, "platform": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "collectionStatus": { "type": "string", "enum": [ "pending", "collecting", "completed", "failed", "stale" ] }, "current": { "type": "object", "required": [ "likeCount", "commentCount", "shareCount", "saveCount", "impressionCount", "reachCount", "linkClickCount" ], "properties": { "likeCount": { "type": "number" }, "commentCount": { "type": "number" }, "shareCount": { "type": "number" }, "saveCount": { "type": "number" }, "impressionCount": { "type": "number" }, "reachCount": { "type": "number" }, "linkClickCount": { "type": "number" } }, "additionalProperties": false }, "derivedMetrics": { "type": "object", "required": [ "engagementRate", "performanceScore", "viralityScore", "qualityScore", "banditReward" ], "properties": { "engagementRate": { "type": "number" }, "performanceScore": { "type": "number", "description": "a number between 0 and 100", "title": "between(0, 100)", "minimum": 0, "maximum": 100 }, "viralityScore": { "type": "number" }, "qualityScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "banditReward": { "type": "number" } }, "additionalProperties": false }, "content": { "type": "object", "required": [ "contentType", "isThread", "caption", "title", "assetCount", "assetTypes", "assetCategories", "aiTags", "categories", "emotions", "purposes", "titles", "descriptions", "durationSecondsMax", "durationSecondsTotal", "widthMax", "heightMax", "fps", "assets" ], "properties": { "contentType": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel" ], "description": "Content format of a post: text_post (text only), text_image, text_video, or carousel (2+ photos).", "examples": [ "text_post", "text_image" ] }, "isThread": { "type": "boolean" }, "caption": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assetCount": { "type": "number" }, "assetTypes": { "type": "array", "items": { "type": "string" } }, "assetCategories": { "type": "array", "items": { "type": "string" } }, "aiTags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "emotions": { "type": "array", "items": { "type": "string" } }, "purposes": { "type": "array", "items": { "type": "string" } }, "titles": { "type": "array", "items": { "type": "string" } }, "descriptions": { "type": "array", "items": { "type": "string" } }, "durationSecondsMax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationSecondsTotal": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "widthMax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "heightMax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "assets": { "type": "array", "items": { "type": "object", "required": [ "assetId", "assetType", "aiTitle", "aiDescription", "aiTags", "contentCategory", "emotion", "purpose", "durationSeconds", "width", "height", "fps", "analysis" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "assetType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTags": { "type": "array", "items": { "type": "string" } }, "contentCategory": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emotion": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "purpose": { "type": "array", "items": { "type": "string" } }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "analysis": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] } }, "additionalProperties": false } } }, "additionalProperties": false }, "lastCollectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshots": { "type": "array", "items": { "type": "object", "required": [ "hoursSincePost", "snapshotTakenAt", "likeCount", "commentCount", "shareCount", "saveCount", "impressionCount", "reachCount", "linkClickCount" ], "properties": { "hoursSincePost": { "$ref": "#/components/schemas/Int" }, "snapshotTakenAt": { "type": "string" }, "likeCount": { "type": "number" }, "commentCount": { "type": "number" }, "shareCount": { "type": "number" }, "saveCount": { "type": "number" }, "impressionCount": { "type": "number" }, "reachCount": { "type": "number" }, "linkClickCount": { "type": "number" }, "collectionError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Return stored performance metrics for a single post. When the post was published to several accounts this resolves the most recently scheduled leg; use getScheduledPostPerformance for one specific leg. Free: reads stored metrics only, with no live provider calls. Use listPostPerformance to compare metrics across many posts at once.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.getPostPerformance({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.get_post_performance(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark analytics post \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/performance\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/performance';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Post performance", "x-displayName": "Post performance" } }, "/v1/teams/{teamId}/posts/performance": { "get": { "tags": [ "Analytics" ], "operationId": "social.listPostPerformance", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, "required": false, "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "Page size as a positive integer string; defaults to 25, capped at 100.", "default": "25", "examples": [ "25", "100" ] }, "required": false, "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "engagement_rate", "impression_count", "like_count", "comment_count", "share_count", "link_click_count", "performance_score", "virality_score", "" ], "description": "Performance sort key, one of: engagement_rate, impression_count, like_count, comment_count, share_count, link_click_count, performance_score, virality_score. Empty or omitted falls back to the default ordering." }, "required": false, "description": "Performance sort key, one of: engagement_rate, impression_count, like_count, comment_count, share_count, link_click_count, performance_score, virality_score. Empty or omitted falls back to the default ordering." }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc", "" ], "description": "Sort direction, asc or desc (default desc). Empty behaves as omitted." }, "required": false, "description": "Sort direction, asc or desc (default desc). Empty behaves as omitted." }, { "name": "from", "in": "query", "schema": { "type": "string", "description": "Start of the published-at window, ISO 8601 timestamp (inclusive).", "examples": [ "2026-05-01T00:00:00.000Z" ] }, "required": false, "description": "Start of the published-at window, ISO 8601 timestamp (inclusive)." }, { "name": "to", "in": "query", "schema": { "type": "string", "description": "End of the published-at window, ISO 8601 timestamp (inclusive).", "examples": [ "2026-05-31T23:59:59.000Z" ] }, "required": false, "description": "End of the published-at window, ISO 8601 timestamp (inclusive)." }, { "name": "platform", "in": "query", "schema": { "anyOf": [ { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, { "type": "string", "enum": [ "" ] } ], "description": "Restrict results to one provider; empty or omitted includes all connected providers." }, "required": false, "description": "Restrict results to one provider; empty or omitted includes all connected providers." }, { "name": "postType", "in": "query", "schema": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel", "thread", "" ], "description": "Restrict results to one content format; empty or omitted includes all formats." }, "required": false, "description": "Restrict results to one content format; empty or omitted includes all formats." }, { "name": "tagIds", "in": "query", "schema": { "type": "string", "description": "CSV of user-tag UUIDs; restricts results to posts assigned ANY of these tags." }, "required": false, "description": "CSV of user-tag UUIDs; restricts results to posts assigned ANY of these tags." }, { "name": "filter[from]", "in": "query", "schema": { "type": "string", "description": "Alias of from using the filter[...] convention; ISO 8601 timestamp.", "examples": [ "2026-05-01T00:00:00.000Z" ] }, "required": false, "description": "Alias of from using the filter[...] convention; ISO 8601 timestamp." }, { "name": "filter[to]", "in": "query", "schema": { "type": "string", "description": "Alias of to using the filter[...] convention; ISO 8601 timestamp.", "examples": [ "2026-05-31T23:59:59.000Z" ] }, "required": false, "description": "Alias of to using the filter[...] convention; ISO 8601 timestamp." }, { "name": "filter[platform]", "in": "query", "schema": { "anyOf": [ { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, { "type": "string", "enum": [ "" ] } ], "description": "Alias of platform using the filter[...] convention." }, "required": false, "description": "Alias of platform using the filter[...] convention." }, { "name": "filter[postType]", "in": "query", "schema": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel", "thread", "" ], "description": "Alias of postType using the filter[...] convention." }, "required": false, "description": "Alias of postType using the filter[...] convention." }, { "name": "filter[tagIds]", "in": "query", "schema": { "type": "string", "description": "Alias of tagIds using the filter[...] convention; CSV of user-tag UUIDs." }, "required": false, "description": "Alias of tagIds using the filter[...] convention; CSV of user-tag UUIDs." }, { "name": "filter[tags]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI tags; matches posts whose assets carry any of the listed tags (OR).", "examples": [ "launch,product" ] }, "required": false, "description": "Comma-separated AI tags; matches posts whose assets carry any of the listed tags (OR)." }, { "name": "filter[category]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI content categories; matches posts in any of the listed categories (OR).", "examples": [ "education" ] }, "required": false, "description": "Comma-separated AI content categories; matches posts in any of the listed categories (OR)." }, { "name": "filter[purpose]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI purposes; matches posts whose assets carry any of the listed purposes (OR).", "examples": [ "promotion" ] }, "required": false, "description": "Comma-separated AI purposes; matches posts whose assets carry any of the listed purposes (OR)." }, { "name": "filter[emotion]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI emotions; matches posts tagged with any of the listed emotions (OR).", "examples": [ "joy" ] }, "required": false, "description": "Comma-separated AI emotions; matches posts tagged with any of the listed emotions (OR)." }, { "name": "filter[mediaType]", "in": "query", "schema": { "type": "string", "description": "Comma-separated media types; each value one of: image, video, audio, gif, document.", "examples": [ "image,video" ] }, "required": false, "description": "Comma-separated media types; each value one of: image, video, audio, gif, document." }, { "name": "filter[enrichmentStatus]", "in": "query", "schema": { "type": "string", "description": "Comma-separated AI enrichment statuses; each value one of: pending, processing, completed, failed.", "examples": [ "completed" ] }, "required": false, "description": "Comma-separated AI enrichment statuses; each value one of: pending, processing, completed, failed." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "scheduledPostId", "platform", "current", "engagementRate", "performanceScore", "content" ], "properties": { "scheduledPostId": { "$ref": "#/components/schemas/UUID" }, "platform": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "current": { "type": "object", "required": [ "likeCount", "commentCount", "shareCount", "saveCount", "impressionCount", "reachCount", "linkClickCount" ], "properties": { "likeCount": { "type": "number" }, "commentCount": { "type": "number" }, "shareCount": { "type": "number" }, "saveCount": { "type": "number" }, "impressionCount": { "type": "number" }, "reachCount": { "type": "number" }, "linkClickCount": { "type": "number" } }, "additionalProperties": false }, "engagementRate": { "type": "number" }, "performanceScore": { "type": "number", "description": "a number between 0 and 100", "title": "between(0, 100)", "minimum": 0, "maximum": 100 }, "content": { "type": "object", "required": [ "contentType", "isThread", "caption", "title", "assetCount", "assetTypes", "assetCategories", "aiTags", "categories", "emotions", "purposes", "titles", "descriptions", "durationSecondsMax", "durationSecondsTotal", "widthMax", "heightMax", "fps", "assets" ], "properties": { "contentType": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel" ], "description": "Content format of a post: text_post (text only), text_image, text_video, or carousel (2+ photos).", "examples": [ "text_post", "text_image" ] }, "isThread": { "type": "boolean" }, "caption": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assetCount": { "type": "number" }, "assetTypes": { "type": "array", "items": { "type": "string" } }, "assetCategories": { "type": "array", "items": { "type": "string" } }, "aiTags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "emotions": { "type": "array", "items": { "type": "string" } }, "purposes": { "type": "array", "items": { "type": "string" } }, "titles": { "type": "array", "items": { "type": "string" } }, "descriptions": { "type": "array", "items": { "type": "string" } }, "durationSecondsMax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationSecondsTotal": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "widthMax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "heightMax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "assets": { "type": "array", "items": { "type": "object", "required": [ "assetId", "assetType", "aiTitle", "aiDescription", "aiTags", "contentCategory", "emotion", "purpose", "durationSeconds", "width", "height", "fps", "analysis" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "assetType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTags": { "type": "array", "items": { "type": "string" } }, "contentCategory": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emotion": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "purpose": { "type": "array", "items": { "type": "string" } }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "analysis": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] } }, "additionalProperties": false } } }, "additionalProperties": false }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userTags": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "colour" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" } }, "additionalProperties": false } }, "lastCollectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List stored performance metrics across many of a team's posts, with filtering and pagination. Free: reads stored metrics only, with no live provider calls. Use getPostPerformance for one post's detail or getAnalyticsAggregates for a team-wide summary.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.listPostPerformance({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.list_post_performance(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark analytics posts \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"query\":{\"from\":\"from\",\"to\":\"to\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/performance\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/performance';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List post performance", "x-displayName": "List post performance" } }, "/v1/teams/{teamId}/scheduled-posts/{scheduledPostId}/performance": { "get": { "tags": [ "Analytics" ], "operationId": "social.getScheduledPostPerformance", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "scheduledPostId", "in": "path", "schema": { "type": "string", "description": "Scheduled-post leg id (UUID). One post fans out to one leg per target account; the leg carries the provider + platform post id used to read its comments." }, "required": true, "description": "Scheduled-post leg id (UUID). One post fans out to one leg per target account; the leg carries the provider + platform post id used to read its comments." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "scheduledPostId", "platform", "collectionStatus", "current", "derivedMetrics", "content", "snapshots" ], "properties": { "scheduledPostId": { "$ref": "#/components/schemas/UUID" }, "platform": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, "collectionStatus": { "type": "string", "enum": [ "pending", "collecting", "completed", "failed", "stale" ] }, "current": { "type": "object", "required": [ "likeCount", "commentCount", "shareCount", "saveCount", "impressionCount", "reachCount", "linkClickCount" ], "properties": { "likeCount": { "type": "number" }, "commentCount": { "type": "number" }, "shareCount": { "type": "number" }, "saveCount": { "type": "number" }, "impressionCount": { "type": "number" }, "reachCount": { "type": "number" }, "linkClickCount": { "type": "number" } }, "additionalProperties": false }, "derivedMetrics": { "type": "object", "required": [ "engagementRate", "performanceScore", "viralityScore", "qualityScore", "banditReward" ], "properties": { "engagementRate": { "type": "number" }, "performanceScore": { "type": "number", "description": "a number between 0 and 100", "title": "between(0, 100)", "minimum": 0, "maximum": 100 }, "viralityScore": { "type": "number" }, "qualityScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "banditReward": { "type": "number" } }, "additionalProperties": false }, "content": { "type": "object", "required": [ "contentType", "isThread", "caption", "title", "assetCount", "assetTypes", "assetCategories", "aiTags", "categories", "emotions", "purposes", "titles", "descriptions", "durationSecondsMax", "durationSecondsTotal", "widthMax", "heightMax", "fps", "assets" ], "properties": { "contentType": { "type": "string", "enum": [ "text_post", "text_image", "text_video", "carousel" ], "description": "Content format of a post: text_post (text only), text_image, text_video, or carousel (2+ photos).", "examples": [ "text_post", "text_image" ] }, "isThread": { "type": "boolean" }, "caption": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assetCount": { "type": "number" }, "assetTypes": { "type": "array", "items": { "type": "string" } }, "assetCategories": { "type": "array", "items": { "type": "string" } }, "aiTags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "emotions": { "type": "array", "items": { "type": "string" } }, "purposes": { "type": "array", "items": { "type": "string" } }, "titles": { "type": "array", "items": { "type": "string" } }, "descriptions": { "type": "array", "items": { "type": "string" } }, "durationSecondsMax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationSecondsTotal": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "widthMax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "heightMax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "assets": { "type": "array", "items": { "type": "object", "required": [ "assetId", "assetType", "aiTitle", "aiDescription", "aiTags", "contentCategory", "emotion", "purpose", "durationSeconds", "width", "height", "fps", "analysis" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "assetType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTags": { "type": "array", "items": { "type": "string" } }, "contentCategory": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emotion": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "purpose": { "type": "array", "items": { "type": "string" } }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "analysis": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] } }, "additionalProperties": false } } }, "additionalProperties": false }, "lastCollectedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapshots": { "type": "array", "items": { "type": "object", "required": [ "hoursSincePost", "snapshotTakenAt", "likeCount", "commentCount", "shareCount", "saveCount", "impressionCount", "reachCount", "linkClickCount" ], "properties": { "hoursSincePost": { "$ref": "#/components/schemas/Int" }, "snapshotTakenAt": { "type": "string" }, "likeCount": { "type": "number" }, "commentCount": { "type": "number" }, "shareCount": { "type": "number" }, "saveCount": { "type": "number" }, "impressionCount": { "type": "number" }, "reachCount": { "type": "number" }, "linkClickCount": { "type": "number" }, "collectionError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Return stored performance metrics for one published scheduled-post leg. Performance rows are collected per leg, so this is the exact drill-down for listPostPerformance rows (which carry scheduledPostId). Free: reads stored metrics only, with no live provider calls.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.social.getScheduledPostPerformance({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n scheduledPostId: process.env.OCTOSPARK_SCHEDULED_POST_ID ?? \"scheduledPostId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.social.get_scheduled_post_performance(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n scheduledPostId=os.environ.get(\"OCTOSPARK_SCHEDULED_POST_ID\", \"scheduledPostId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark analytics scheduled-post \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"scheduledPostId\":\"scheduledPostId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let scheduled_post_id = env::var(\"OCTOSPARK_SCHEDULED_POST_ID\").unwrap_or_else(|_| \"scheduledPostId\".to_string());\n let url = format!(\"{}/v1/teams/{}/scheduled-posts/{}/performance\", base_url.trim_end_matches('/'), team_id, scheduled_post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final scheduledPostId = Platform.environment['OCTOSPARK_SCHEDULED_POST_ID'] ?? 'scheduledPostId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/scheduled-posts/$scheduledPostId/performance';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Scheduled post performance", "x-displayName": "Scheduled post performance" } }, "/v1/teams/{teamId}/assets": { "get": { "tags": [ "Assets" ], "operationId": "assets.listAssets", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, "required": false, "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "Page size as a positive integer string; defaults to 25, capped at 100.", "default": "25", "examples": [ "25", "100" ] }, "required": false, "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt.", "examples": [ "createdAt" ] }, "required": false, "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt." }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc or desc; defaults to desc.", "default": "desc" }, "required": false, "description": "Sort direction: asc or desc; defaults to desc." }, { "name": "filter[assetType]", "in": "query", "schema": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ], "description": "Restrict results to one media type (e.g. image or video)." }, "required": false, "description": "Restrict results to one media type (e.g. image or video)." }, { "name": "filter[assetCategory]", "in": "query", "schema": { "type": "string", "enum": [ "user_upload", "render", "template", "green_screen_template", "sound_effect", "music", "brand_asset", "ai_image", "ai_video", "other" ], "description": "Restrict results to one AI-assigned asset category." }, "required": false, "description": "Restrict results to one AI-assigned asset category." }, { "name": "filter[folderId]", "in": "query", "schema": { "type": "string", "description": "Restrict results to one folder by uuid, or the literal \"root\" for assets outside any folder.", "examples": [ "root" ], "pattern": "^(root|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "required": false, "description": "Restrict results to one folder by uuid, or the literal \"root\" for assets outside any folder." }, { "name": "filter[folderKind]", "in": "query", "schema": { "type": "string", "enum": [ "chat_uploads" ], "description": "Set to \"chat_uploads\" to list ONLY the per-team chat-uploads folder; absent excludes it (the default Media Library view)." }, "required": false, "description": "Set to \"chat_uploads\" to list ONLY the per-team chat-uploads folder; absent excludes it (the default Media Library view)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "originalFilename", "fileSize", "mimeType", "assetType", "assetCategory", "assetTypeData", "storagePath", "thumbnailPath", "aiTitle", "aiDescription", "aiAltText", "aiTags", "contentHash", "processingStatus", "processingError", "isDeleted", "deletedAt", "hardDeletedAt", "sharedWithOrg", "folderId", "folderName", "displayName", "aspectRatio", "isProcessing", "createdAt", "updatedAt", "thumbnailUrl", "fileUrl", "previewUrlsExpireAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "originalFilename": { "type": "string" }, "fileSize": { "type": "number" }, "mimeType": { "type": "string" }, "assetType": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ] }, "assetCategory": { "type": "string", "enum": [ "user_upload", "render", "template", "green_screen_template", "sound_effect", "music", "brand_asset", "ai_image", "ai_video", "other" ] }, "assetTypeData": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "type", "width", "height", "format" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "format": { "type": "string" }, "colorSpace": { "type": "string" }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "video" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "duration": { "type": "number" }, "codec": { "type": "string" }, "bitrate": { "type": "number" }, "fps": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "audio" ] }, "duration": { "type": "number" }, "sampleRate": { "type": "number" }, "channels": { "type": "number" }, "codec": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "frameCount" ], "properties": { "type": { "type": "string", "enum": [ "gif" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "frameCount": { "type": "number" }, "duration": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "format" ], "properties": { "type": { "type": "string", "enum": [ "document" ] }, "pageCount": { "type": "number" }, "format": { "type": "string" } }, "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "chromaKey", "analysisVersion", "confidence", "chromaKeyProfiles", "subjectAnalysis", "aspectRatioProfiles", "captioning", "audio", "composition" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "green_screen_template" ] }, "chromaKey": { "type": "object", "required": [ "keyColor", "ffmpegSimilarity", "ffmpegBlend", "spillRisk" ], "properties": { "keyColor": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}$", "pattern": "^#[0-9a-fA-F]{6}$" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" }, "spillRisk": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "additionalProperties": false }, "analysisVersion": { "type": "number" }, "confidence": { "type": "number" }, "chromaKeyProfiles": { "type": "object", "required": [ "baseline", "fallback" ], "properties": { "baseline": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "fallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "confidence": { "type": "number" }, "strongFallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "subjectAnalysis": { "type": "object", "required": [ "sampleCount", "sampleTimestampsSeconds", "representativeBounds", "subjectHeightFraction", "subjectWidthFraction", "centerXFraction", "bottomYFraction", "cropRisk", "faceRegion", "confidence" ], "properties": { "sampleCount": { "type": "number" }, "sampleTimestampsSeconds": { "type": "array", "items": { "type": "number" } }, "representativeBounds": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "defaultSubjectBounds": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "subjectHeightFraction": { "type": "number" }, "subjectWidthFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "bottomYFraction": { "type": "number" }, "cropRisk": { "type": "object", "required": [ "top", "bottom", "left", "right" ], "properties": { "top": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" }, "right": { "type": "number" } }, "additionalProperties": false }, "defaultFaceRegion": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRange": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRangeDelta": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "additionalProperties": false }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegion": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "confidence": { "type": "number" } }, "additionalProperties": false }, "aspectRatioProfiles": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "captioning": { "type": "object", "required": [ "preferredCaptionZones", "forbiddenCaptionZones", "subjectBoundsByAspectRatio", "faceRegionByAspectRatio", "captionSafeBandsByAspectRatio", "preferredZonesByAspectRatio", "forbiddenZonesByAspectRatio" ], "properties": { "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "16:9": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "1:1": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "4:5": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false }, "preferredZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "forbiddenZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "audio": { "type": "object", "required": [ "hasAudio", "likelyHasMusic", "likelyHasSpeech", "needsMusic" ], "properties": { "hasAudio": { "type": "boolean" }, "likelyHasMusic": { "type": "boolean" }, "likelyHasSpeech": { "type": "boolean" }, "needsMusic": { "type": "boolean" } }, "additionalProperties": false }, "composition": { "type": "object", "required": [ "safeCaptionZones", "captionSafeBandsByAspectRatio", "recommendedBackgroundTags", "recommendedMusicTags", "recommendedSoundEffectTags" ], "properties": { "safeCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "recommendedBackgroundTags": { "type": "array", "items": { "type": "string" } }, "recommendedMusicTags": { "type": "array", "items": { "type": "string" } }, "recommendedSoundEffectTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "aspectRatioCategory" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "background" ] }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatioCategory": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "other" ] }, "dominantColors": { "type": "array", "items": { "type": "string" } }, "isLoopable": { "type": "boolean" }, "textSafeZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "mood", "energyLevel" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "music" ] }, "mood": { "type": "array", "items": { "type": "string" } }, "energyLevel": { "type": "string", "enum": [ "low", "medium", "high", "variable" ] }, "tempo": { "type": "string", "enum": [ "slow", "medium", "fast", "variable" ] }, "hasVocals": { "type": "boolean" }, "isLoopable": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "effectCategory", "intensity", "timingUse" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "sound_effect" ] }, "effectCategory": { "type": "string" }, "intensity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "timingUse": { "type": "string", "enum": [ "intro", "impact", "reaction", "transition", "outro" ] } }, "additionalProperties": false } ] } ] }, { "type": "null" } ] }, "storagePath": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiAltText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTags": { "type": "array", "items": { "type": "string" } }, "contentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "processingError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDeleted": { "type": "boolean" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hardDeletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sharedWithOrg": { "type": "boolean" }, "folderId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "folderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "type": "string" }, "aspectRatio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isProcessing": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Signed URL of the generated thumbnail, or null when the asset has none." }, "fileUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Signed URL of the original file, included only for images and videos without a thumbnail (the preview renders the original instead). Null otherwise; use getAssetSignedUrl for full-size access." }, "previewUrlsExpireAt": { "type": "string", "description": "ISO-8601 time when thumbnailUrl and fileUrl stop working. Refetch the list before this time rather than signing assets one by one." } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List a team's active media assets with pagination and optional filters such as folder. Each item carries signed preview URLs (thumbnailUrl, fileUrl) valid until previewUrlsExpireAt, so render a grid from this one response and refetch it before expiry instead of signing assets one by one. Trashed assets are excluded; use listTrash for those. To find assets by content, prefer searchAssets (free keyword) or searchAgenticAssets (paid semantic).", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.listAssets({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.list_assets(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets list \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/assets\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/assets';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List assets", "x-displayName": "List assets" } }, "/v1/teams/{teamId}/assets/{assetId}": { "get": { "tags": [ "Assets" ], "operationId": "assets.getAsset", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "assetId", "in": "path", "schema": { "type": "string", "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." }, "required": true, "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "originalFilename", "fileSize", "mimeType", "assetType", "assetCategory", "assetTypeData", "storagePath", "thumbnailPath", "aiTitle", "aiDescription", "aiAltText", "aiTags", "contentHash", "processingStatus", "processingError", "isDeleted", "deletedAt", "hardDeletedAt", "sharedWithOrg", "folderId", "folderName", "displayName", "aspectRatio", "isProcessing", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "originalFilename": { "type": "string" }, "fileSize": { "type": "number" }, "mimeType": { "type": "string" }, "assetType": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ] }, "assetCategory": { "type": "string", "enum": [ "user_upload", "render", "template", "green_screen_template", "sound_effect", "music", "brand_asset", "ai_image", "ai_video", "other" ] }, "assetTypeData": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "type", "width", "height", "format" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "format": { "type": "string" }, "colorSpace": { "type": "string" }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "video" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "duration": { "type": "number" }, "codec": { "type": "string" }, "bitrate": { "type": "number" }, "fps": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "audio" ] }, "duration": { "type": "number" }, "sampleRate": { "type": "number" }, "channels": { "type": "number" }, "codec": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "frameCount" ], "properties": { "type": { "type": "string", "enum": [ "gif" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "frameCount": { "type": "number" }, "duration": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "format" ], "properties": { "type": { "type": "string", "enum": [ "document" ] }, "pageCount": { "type": "number" }, "format": { "type": "string" } }, "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "chromaKey", "analysisVersion", "confidence", "chromaKeyProfiles", "subjectAnalysis", "aspectRatioProfiles", "captioning", "audio", "composition" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "green_screen_template" ] }, "chromaKey": { "type": "object", "required": [ "keyColor", "ffmpegSimilarity", "ffmpegBlend", "spillRisk" ], "properties": { "keyColor": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}$", "pattern": "^#[0-9a-fA-F]{6}$" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" }, "spillRisk": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "additionalProperties": false }, "analysisVersion": { "type": "number" }, "confidence": { "type": "number" }, "chromaKeyProfiles": { "type": "object", "required": [ "baseline", "fallback" ], "properties": { "baseline": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "fallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "confidence": { "type": "number" }, "strongFallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "subjectAnalysis": { "type": "object", "required": [ "sampleCount", "sampleTimestampsSeconds", "representativeBounds", "subjectHeightFraction", "subjectWidthFraction", "centerXFraction", "bottomYFraction", "cropRisk", "faceRegion", "confidence" ], "properties": { "sampleCount": { "type": "number" }, "sampleTimestampsSeconds": { "type": "array", "items": { "type": "number" } }, "representativeBounds": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "defaultSubjectBounds": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "subjectHeightFraction": { "type": "number" }, "subjectWidthFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "bottomYFraction": { "type": "number" }, "cropRisk": { "type": "object", "required": [ "top", "bottom", "left", "right" ], "properties": { "top": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" }, "right": { "type": "number" } }, "additionalProperties": false }, "defaultFaceRegion": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRange": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRangeDelta": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "additionalProperties": false }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegion": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "confidence": { "type": "number" } }, "additionalProperties": false }, "aspectRatioProfiles": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "captioning": { "type": "object", "required": [ "preferredCaptionZones", "forbiddenCaptionZones", "subjectBoundsByAspectRatio", "faceRegionByAspectRatio", "captionSafeBandsByAspectRatio", "preferredZonesByAspectRatio", "forbiddenZonesByAspectRatio" ], "properties": { "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "16:9": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "1:1": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "4:5": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false }, "preferredZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "forbiddenZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "audio": { "type": "object", "required": [ "hasAudio", "likelyHasMusic", "likelyHasSpeech", "needsMusic" ], "properties": { "hasAudio": { "type": "boolean" }, "likelyHasMusic": { "type": "boolean" }, "likelyHasSpeech": { "type": "boolean" }, "needsMusic": { "type": "boolean" } }, "additionalProperties": false }, "composition": { "type": "object", "required": [ "safeCaptionZones", "captionSafeBandsByAspectRatio", "recommendedBackgroundTags", "recommendedMusicTags", "recommendedSoundEffectTags" ], "properties": { "safeCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "recommendedBackgroundTags": { "type": "array", "items": { "type": "string" } }, "recommendedMusicTags": { "type": "array", "items": { "type": "string" } }, "recommendedSoundEffectTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "aspectRatioCategory" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "background" ] }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatioCategory": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "other" ] }, "dominantColors": { "type": "array", "items": { "type": "string" } }, "isLoopable": { "type": "boolean" }, "textSafeZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "mood", "energyLevel" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "music" ] }, "mood": { "type": "array", "items": { "type": "string" } }, "energyLevel": { "type": "string", "enum": [ "low", "medium", "high", "variable" ] }, "tempo": { "type": "string", "enum": [ "slow", "medium", "fast", "variable" ] }, "hasVocals": { "type": "boolean" }, "isLoopable": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "effectCategory", "intensity", "timingUse" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "sound_effect" ] }, "effectCategory": { "type": "string" }, "intensity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "timingUse": { "type": "string", "enum": [ "intro", "impact", "reaction", "transition", "outro" ] } }, "additionalProperties": false } ] } ] }, { "type": "null" } ] }, "storagePath": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiAltText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTags": { "type": "array", "items": { "type": "string" } }, "contentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "processingError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDeleted": { "type": "boolean" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hardDeletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sharedWithOrg": { "type": "boolean" }, "folderId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "folderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "type": "string" }, "aspectRatio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isProcessing": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Fetch a single asset by id, including its metadata, processing status, and folder placement. Use listAssets or the search endpoints to discover asset ids first.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.getAsset({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n assetId: process.env.OCTOSPARK_ASSET_ID ?? \"assetId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.get_asset(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n assetId=os.environ.get(\"OCTOSPARK_ASSET_ID\", \"assetId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets get \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"assetId\":\"assetId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let asset_id = env::var(\"OCTOSPARK_ASSET_ID\").unwrap_or_else(|_| \"assetId\".to_string());\n let url = format!(\"{}/v1/teams/{}/assets/{}\", base_url.trim_end_matches('/'), team_id, asset_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final assetId = Platform.environment['OCTOSPARK_ASSET_ID'] ?? 'assetId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/assets/$assetId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Asset", "x-displayName": "Asset" }, "patch": { "tags": [ "Assets" ], "operationId": "assets.updateAssetMetadata", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "assetId", "in": "path", "schema": { "type": "string", "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." }, "required": true, "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "originalFilename", "fileSize", "mimeType", "assetType", "assetCategory", "assetTypeData", "storagePath", "thumbnailPath", "aiTitle", "aiDescription", "aiAltText", "aiTags", "contentHash", "processingStatus", "processingError", "isDeleted", "deletedAt", "hardDeletedAt", "sharedWithOrg", "folderId", "folderName", "displayName", "aspectRatio", "isProcessing", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "originalFilename": { "type": "string" }, "fileSize": { "type": "number" }, "mimeType": { "type": "string" }, "assetType": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ] }, "assetCategory": { "type": "string", "enum": [ "user_upload", "render", "template", "green_screen_template", "sound_effect", "music", "brand_asset", "ai_image", "ai_video", "other" ] }, "assetTypeData": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "type", "width", "height", "format" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "format": { "type": "string" }, "colorSpace": { "type": "string" }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "video" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "duration": { "type": "number" }, "codec": { "type": "string" }, "bitrate": { "type": "number" }, "fps": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "audio" ] }, "duration": { "type": "number" }, "sampleRate": { "type": "number" }, "channels": { "type": "number" }, "codec": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "frameCount" ], "properties": { "type": { "type": "string", "enum": [ "gif" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "frameCount": { "type": "number" }, "duration": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "format" ], "properties": { "type": { "type": "string", "enum": [ "document" ] }, "pageCount": { "type": "number" }, "format": { "type": "string" } }, "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "chromaKey", "analysisVersion", "confidence", "chromaKeyProfiles", "subjectAnalysis", "aspectRatioProfiles", "captioning", "audio", "composition" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "green_screen_template" ] }, "chromaKey": { "type": "object", "required": [ "keyColor", "ffmpegSimilarity", "ffmpegBlend", "spillRisk" ], "properties": { "keyColor": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}$", "pattern": "^#[0-9a-fA-F]{6}$" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" }, "spillRisk": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "additionalProperties": false }, "analysisVersion": { "type": "number" }, "confidence": { "type": "number" }, "chromaKeyProfiles": { "type": "object", "required": [ "baseline", "fallback" ], "properties": { "baseline": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "fallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "confidence": { "type": "number" }, "strongFallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "subjectAnalysis": { "type": "object", "required": [ "sampleCount", "sampleTimestampsSeconds", "representativeBounds", "subjectHeightFraction", "subjectWidthFraction", "centerXFraction", "bottomYFraction", "cropRisk", "faceRegion", "confidence" ], "properties": { "sampleCount": { "type": "number" }, "sampleTimestampsSeconds": { "type": "array", "items": { "type": "number" } }, "representativeBounds": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "defaultSubjectBounds": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "subjectHeightFraction": { "type": "number" }, "subjectWidthFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "bottomYFraction": { "type": "number" }, "cropRisk": { "type": "object", "required": [ "top", "bottom", "left", "right" ], "properties": { "top": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" }, "right": { "type": "number" } }, "additionalProperties": false }, "defaultFaceRegion": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRange": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRangeDelta": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "additionalProperties": false }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegion": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "confidence": { "type": "number" } }, "additionalProperties": false }, "aspectRatioProfiles": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "captioning": { "type": "object", "required": [ "preferredCaptionZones", "forbiddenCaptionZones", "subjectBoundsByAspectRatio", "faceRegionByAspectRatio", "captionSafeBandsByAspectRatio", "preferredZonesByAspectRatio", "forbiddenZonesByAspectRatio" ], "properties": { "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "16:9": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "1:1": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "4:5": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false }, "preferredZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "forbiddenZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "audio": { "type": "object", "required": [ "hasAudio", "likelyHasMusic", "likelyHasSpeech", "needsMusic" ], "properties": { "hasAudio": { "type": "boolean" }, "likelyHasMusic": { "type": "boolean" }, "likelyHasSpeech": { "type": "boolean" }, "needsMusic": { "type": "boolean" } }, "additionalProperties": false }, "composition": { "type": "object", "required": [ "safeCaptionZones", "captionSafeBandsByAspectRatio", "recommendedBackgroundTags", "recommendedMusicTags", "recommendedSoundEffectTags" ], "properties": { "safeCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "recommendedBackgroundTags": { "type": "array", "items": { "type": "string" } }, "recommendedMusicTags": { "type": "array", "items": { "type": "string" } }, "recommendedSoundEffectTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "aspectRatioCategory" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "background" ] }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatioCategory": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "other" ] }, "dominantColors": { "type": "array", "items": { "type": "string" } }, "isLoopable": { "type": "boolean" }, "textSafeZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "mood", "energyLevel" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "music" ] }, "mood": { "type": "array", "items": { "type": "string" } }, "energyLevel": { "type": "string", "enum": [ "low", "medium", "high", "variable" ] }, "tempo": { "type": "string", "enum": [ "slow", "medium", "fast", "variable" ] }, "hasVocals": { "type": "boolean" }, "isLoopable": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "effectCategory", "intensity", "timingUse" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "sound_effect" ] }, "effectCategory": { "type": "string" }, "intensity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "timingUse": { "type": "string", "enum": [ "intro", "impact", "reaction", "transition", "outro" ] } }, "additionalProperties": false } ] } ] }, { "type": "null" } ] }, "storagePath": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiAltText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTags": { "type": "array", "items": { "type": "string" } }, "contentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "processingError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDeleted": { "type": "boolean" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hardDeletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sharedWithOrg": { "type": "boolean" }, "folderId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "folderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "type": "string" }, "aspectRatio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isProcessing": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Edit an asset title, description, accessibility alt text, tags or organisation sharing. Omitted fields keep their current values; null clears a nullable text field and an empty tag array clears tags. This operation does not spend credits.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Asset title shown in the media library; omit to keep the current title or send null to clear it." }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Description of the asset content; omit to keep the current description or send null to clear it." }, "aiAltText": { "anyOf": [ { "type": "string", "description": "a string at most 1000 character(s) long", "title": "maxLength(1000)", "maxLength": 1000 }, { "type": "null" } ], "description": "Accessibility alt text for visual media, max 1000 characters; null clears it. Propagated to social providers that support per-image alt text." }, "aiTags": { "type": "array", "items": { "type": "string" }, "description": "Replace the asset tags with this list; omit to keep existing tags or send an empty array to clear them." }, "sharedWithOrg": { "type": "boolean", "description": "Whether other teams in the organisation can use this asset; omit to keep its current sharing setting." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.updateAssetMetadata({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n assetId: process.env.OCTOSPARK_ASSET_ID ?? \"assetId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.update_asset_metadata(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n assetId=os.environ.get(\"OCTOSPARK_ASSET_ID\", \"assetId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets update-asset-metadata \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"assetId\":\"assetId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let asset_id = env::var(\"OCTOSPARK_ASSET_ID\").unwrap_or_else(|_| \"assetId\".to_string());\n let url = format!(\"{}/v1/teams/{}/assets/{}\", base_url.trim_end_matches('/'), team_id, asset_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final assetId = Platform.environment['OCTOSPARK_ASSET_ID'] ?? 'assetId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/assets/$assetId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Update asset metadata", "x-displayName": "Update asset metadata" }, "delete": { "tags": [ "Assets" ], "operationId": "assets.softDeleteAsset", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "assetId", "in": "path", "schema": { "type": "string", "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." }, "required": true, "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "originalFilename", "fileSize", "mimeType", "assetType", "assetCategory", "assetTypeData", "storagePath", "thumbnailPath", "aiTitle", "aiDescription", "aiAltText", "aiTags", "contentHash", "processingStatus", "processingError", "isDeleted", "deletedAt", "hardDeletedAt", "sharedWithOrg", "folderId", "folderName", "displayName", "aspectRatio", "isProcessing", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "originalFilename": { "type": "string" }, "fileSize": { "type": "number" }, "mimeType": { "type": "string" }, "assetType": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ] }, "assetCategory": { "type": "string", "enum": [ "user_upload", "render", "template", "green_screen_template", "sound_effect", "music", "brand_asset", "ai_image", "ai_video", "other" ] }, "assetTypeData": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "type", "width", "height", "format" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "format": { "type": "string" }, "colorSpace": { "type": "string" }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "video" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "duration": { "type": "number" }, "codec": { "type": "string" }, "bitrate": { "type": "number" }, "fps": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "audio" ] }, "duration": { "type": "number" }, "sampleRate": { "type": "number" }, "channels": { "type": "number" }, "codec": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "frameCount" ], "properties": { "type": { "type": "string", "enum": [ "gif" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "frameCount": { "type": "number" }, "duration": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "format" ], "properties": { "type": { "type": "string", "enum": [ "document" ] }, "pageCount": { "type": "number" }, "format": { "type": "string" } }, "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "chromaKey", "analysisVersion", "confidence", "chromaKeyProfiles", "subjectAnalysis", "aspectRatioProfiles", "captioning", "audio", "composition" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "green_screen_template" ] }, "chromaKey": { "type": "object", "required": [ "keyColor", "ffmpegSimilarity", "ffmpegBlend", "spillRisk" ], "properties": { "keyColor": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}$", "pattern": "^#[0-9a-fA-F]{6}$" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" }, "spillRisk": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "additionalProperties": false }, "analysisVersion": { "type": "number" }, "confidence": { "type": "number" }, "chromaKeyProfiles": { "type": "object", "required": [ "baseline", "fallback" ], "properties": { "baseline": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "fallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "confidence": { "type": "number" }, "strongFallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "subjectAnalysis": { "type": "object", "required": [ "sampleCount", "sampleTimestampsSeconds", "representativeBounds", "subjectHeightFraction", "subjectWidthFraction", "centerXFraction", "bottomYFraction", "cropRisk", "faceRegion", "confidence" ], "properties": { "sampleCount": { "type": "number" }, "sampleTimestampsSeconds": { "type": "array", "items": { "type": "number" } }, "representativeBounds": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "defaultSubjectBounds": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "subjectHeightFraction": { "type": "number" }, "subjectWidthFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "bottomYFraction": { "type": "number" }, "cropRisk": { "type": "object", "required": [ "top", "bottom", "left", "right" ], "properties": { "top": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" }, "right": { "type": "number" } }, "additionalProperties": false }, "defaultFaceRegion": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRange": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRangeDelta": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "additionalProperties": false }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegion": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "confidence": { "type": "number" } }, "additionalProperties": false }, "aspectRatioProfiles": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "captioning": { "type": "object", "required": [ "preferredCaptionZones", "forbiddenCaptionZones", "subjectBoundsByAspectRatio", "faceRegionByAspectRatio", "captionSafeBandsByAspectRatio", "preferredZonesByAspectRatio", "forbiddenZonesByAspectRatio" ], "properties": { "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "16:9": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "1:1": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "4:5": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false }, "preferredZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "forbiddenZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "audio": { "type": "object", "required": [ "hasAudio", "likelyHasMusic", "likelyHasSpeech", "needsMusic" ], "properties": { "hasAudio": { "type": "boolean" }, "likelyHasMusic": { "type": "boolean" }, "likelyHasSpeech": { "type": "boolean" }, "needsMusic": { "type": "boolean" } }, "additionalProperties": false }, "composition": { "type": "object", "required": [ "safeCaptionZones", "captionSafeBandsByAspectRatio", "recommendedBackgroundTags", "recommendedMusicTags", "recommendedSoundEffectTags" ], "properties": { "safeCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "recommendedBackgroundTags": { "type": "array", "items": { "type": "string" } }, "recommendedMusicTags": { "type": "array", "items": { "type": "string" } }, "recommendedSoundEffectTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "aspectRatioCategory" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "background" ] }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatioCategory": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "other" ] }, "dominantColors": { "type": "array", "items": { "type": "string" } }, "isLoopable": { "type": "boolean" }, "textSafeZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "mood", "energyLevel" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "music" ] }, "mood": { "type": "array", "items": { "type": "string" } }, "energyLevel": { "type": "string", "enum": [ "low", "medium", "high", "variable" ] }, "tempo": { "type": "string", "enum": [ "slow", "medium", "fast", "variable" ] }, "hasVocals": { "type": "boolean" }, "isLoopable": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "effectCategory", "intensity", "timingUse" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "sound_effect" ] }, "effectCategory": { "type": "string" }, "intensity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "timingUse": { "type": "string", "enum": [ "intro", "impact", "reaction", "transition", "outro" ] } }, "additionalProperties": false } ] } ] }, { "type": "null" } ] }, "storagePath": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiAltText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTags": { "type": "array", "items": { "type": "string" } }, "contentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "processingError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDeleted": { "type": "boolean" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hardDeletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sharedWithOrg": { "type": "boolean" }, "folderId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "folderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "type": "string" }, "aspectRatio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isProcessing": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Move an asset to the team's trash (soft delete). It disappears from listings and search but is recoverable via restoreAsset. Check getAssetReferences first if you need to know which posts still reference it.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.softDeleteAsset({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n assetId: process.env.OCTOSPARK_ASSET_ID ?? \"assetId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.soft_delete_asset(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n assetId=os.environ.get(\"OCTOSPARK_ASSET_ID\", \"assetId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets delete \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"assetId\":\"assetId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let asset_id = env::var(\"OCTOSPARK_ASSET_ID\").unwrap_or_else(|_| \"assetId\".to_string());\n let url = format!(\"{}/v1/teams/{}/assets/{}\", base_url.trim_end_matches('/'), team_id, asset_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final assetId = Platform.environment['OCTOSPARK_ASSET_ID'] ?? 'assetId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/assets/$assetId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Soft delete asset", "x-displayName": "Soft delete asset" } }, "/v1/teams/{teamId}/assets/{assetId}/references": { "get": { "tags": [ "Assets" ], "operationId": "assets.getAssetReferences", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "assetId", "in": "path", "schema": { "type": "string", "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." }, "required": true, "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "liveScheduled", "draft" ], "properties": { "liveScheduled": { "type": "object", "required": [ "count", "scheduledPostIds" ], "properties": { "count": { "type": "number" }, "scheduledPostIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false }, "draft": { "type": "object", "required": [ "count", "contentItemIds" ], "properties": { "count": { "type": "number" }, "contentItemIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Summarize where an asset is referenced, such as the posts that use it. Check this before soft-deleting an asset to understand what would be affected.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.getAssetReferences({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n assetId: process.env.OCTOSPARK_ASSET_ID ?? \"assetId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.get_asset_references(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n assetId=os.environ.get(\"OCTOSPARK_ASSET_ID\", \"assetId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets get-asset-references \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"assetId\":\"assetId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let asset_id = env::var(\"OCTOSPARK_ASSET_ID\").unwrap_or_else(|_| \"assetId\".to_string());\n let url = format!(\"{}/v1/teams/{}/assets/{}/references\", base_url.trim_end_matches('/'), team_id, asset_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final assetId = Platform.environment['OCTOSPARK_ASSET_ID'] ?? 'assetId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/assets/$assetId/references';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Asset references", "x-displayName": "Asset references" } }, "/v1/teams/{teamId}/assets/{assetId}/restore": { "post": { "tags": [ "Assets" ], "operationId": "assets.restoreAsset", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "assetId", "in": "path", "schema": { "type": "string", "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." }, "required": true, "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "originalFilename", "fileSize", "mimeType", "assetType", "assetCategory", "assetTypeData", "storagePath", "thumbnailPath", "aiTitle", "aiDescription", "aiAltText", "aiTags", "contentHash", "processingStatus", "processingError", "isDeleted", "deletedAt", "hardDeletedAt", "sharedWithOrg", "folderId", "folderName", "displayName", "aspectRatio", "isProcessing", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "originalFilename": { "type": "string" }, "fileSize": { "type": "number" }, "mimeType": { "type": "string" }, "assetType": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ] }, "assetCategory": { "type": "string", "enum": [ "user_upload", "render", "template", "green_screen_template", "sound_effect", "music", "brand_asset", "ai_image", "ai_video", "other" ] }, "assetTypeData": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "type", "width", "height", "format" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "format": { "type": "string" }, "colorSpace": { "type": "string" }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "video" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "duration": { "type": "number" }, "codec": { "type": "string" }, "bitrate": { "type": "number" }, "fps": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "audio" ] }, "duration": { "type": "number" }, "sampleRate": { "type": "number" }, "channels": { "type": "number" }, "codec": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "frameCount" ], "properties": { "type": { "type": "string", "enum": [ "gif" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "frameCount": { "type": "number" }, "duration": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "format" ], "properties": { "type": { "type": "string", "enum": [ "document" ] }, "pageCount": { "type": "number" }, "format": { "type": "string" } }, "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "chromaKey", "analysisVersion", "confidence", "chromaKeyProfiles", "subjectAnalysis", "aspectRatioProfiles", "captioning", "audio", "composition" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "green_screen_template" ] }, "chromaKey": { "type": "object", "required": [ "keyColor", "ffmpegSimilarity", "ffmpegBlend", "spillRisk" ], "properties": { "keyColor": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}$", "pattern": "^#[0-9a-fA-F]{6}$" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" }, "spillRisk": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "additionalProperties": false }, "analysisVersion": { "type": "number" }, "confidence": { "type": "number" }, "chromaKeyProfiles": { "type": "object", "required": [ "baseline", "fallback" ], "properties": { "baseline": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "fallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "confidence": { "type": "number" }, "strongFallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "subjectAnalysis": { "type": "object", "required": [ "sampleCount", "sampleTimestampsSeconds", "representativeBounds", "subjectHeightFraction", "subjectWidthFraction", "centerXFraction", "bottomYFraction", "cropRisk", "faceRegion", "confidence" ], "properties": { "sampleCount": { "type": "number" }, "sampleTimestampsSeconds": { "type": "array", "items": { "type": "number" } }, "representativeBounds": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "defaultSubjectBounds": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "subjectHeightFraction": { "type": "number" }, "subjectWidthFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "bottomYFraction": { "type": "number" }, "cropRisk": { "type": "object", "required": [ "top", "bottom", "left", "right" ], "properties": { "top": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" }, "right": { "type": "number" } }, "additionalProperties": false }, "defaultFaceRegion": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRange": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRangeDelta": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "additionalProperties": false }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegion": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "confidence": { "type": "number" } }, "additionalProperties": false }, "aspectRatioProfiles": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "captioning": { "type": "object", "required": [ "preferredCaptionZones", "forbiddenCaptionZones", "subjectBoundsByAspectRatio", "faceRegionByAspectRatio", "captionSafeBandsByAspectRatio", "preferredZonesByAspectRatio", "forbiddenZonesByAspectRatio" ], "properties": { "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "16:9": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "1:1": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "4:5": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false }, "preferredZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "forbiddenZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "audio": { "type": "object", "required": [ "hasAudio", "likelyHasMusic", "likelyHasSpeech", "needsMusic" ], "properties": { "hasAudio": { "type": "boolean" }, "likelyHasMusic": { "type": "boolean" }, "likelyHasSpeech": { "type": "boolean" }, "needsMusic": { "type": "boolean" } }, "additionalProperties": false }, "composition": { "type": "object", "required": [ "safeCaptionZones", "captionSafeBandsByAspectRatio", "recommendedBackgroundTags", "recommendedMusicTags", "recommendedSoundEffectTags" ], "properties": { "safeCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "recommendedBackgroundTags": { "type": "array", "items": { "type": "string" } }, "recommendedMusicTags": { "type": "array", "items": { "type": "string" } }, "recommendedSoundEffectTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "aspectRatioCategory" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "background" ] }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatioCategory": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "other" ] }, "dominantColors": { "type": "array", "items": { "type": "string" } }, "isLoopable": { "type": "boolean" }, "textSafeZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "mood", "energyLevel" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "music" ] }, "mood": { "type": "array", "items": { "type": "string" } }, "energyLevel": { "type": "string", "enum": [ "low", "medium", "high", "variable" ] }, "tempo": { "type": "string", "enum": [ "slow", "medium", "fast", "variable" ] }, "hasVocals": { "type": "boolean" }, "isLoopable": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "effectCategory", "intensity", "timingUse" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "sound_effect" ] }, "effectCategory": { "type": "string" }, "intensity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "timingUse": { "type": "string", "enum": [ "intro", "impact", "reaction", "transition", "outro" ] } }, "additionalProperties": false } ] } ] }, { "type": "null" } ] }, "storagePath": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiAltText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTags": { "type": "array", "items": { "type": "string" } }, "contentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "processingError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDeleted": { "type": "boolean" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hardDeletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sharedWithOrg": { "type": "boolean" }, "folderId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "folderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "type": "string" }, "aspectRatio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isProcessing": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Restore a soft-deleted asset from the trash back into the active library, where it reappears in listings and search. Find trashed asset ids via listTrash.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.restoreAsset({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n assetId: process.env.OCTOSPARK_ASSET_ID ?? \"assetId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.restore_asset(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n assetId=os.environ.get(\"OCTOSPARK_ASSET_ID\", \"assetId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets restore-asset \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"assetId\":\"assetId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let asset_id = env::var(\"OCTOSPARK_ASSET_ID\").unwrap_or_else(|_| \"assetId\".to_string());\n let url = format!(\"{}/v1/teams/{}/assets/{}/restore\", base_url.trim_end_matches('/'), team_id, asset_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final assetId = Platform.environment['OCTOSPARK_ASSET_ID'] ?? 'assetId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/assets/$assetId/restore';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.post(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Restore asset", "x-displayName": "Restore asset" } }, "/v1/teams/{teamId}/assets/{assetId}/thumbnail-url": { "get": { "tags": [ "Assets" ], "operationId": "assets.getAssetThumbnailSignedUrl", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "assetId", "in": "path", "schema": { "type": "string", "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." }, "required": true, "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Get a temporary signed URL for an asset thumbnail after checking access. Returns null when no thumbnail is available; use getAssetSignedUrl for the original file. This read is free.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.getAssetThumbnailSignedUrl({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n assetId: process.env.OCTOSPARK_ASSET_ID ?? \"assetId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.get_asset_thumbnail_signed_url(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n assetId=os.environ.get(\"OCTOSPARK_ASSET_ID\", \"assetId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets get-asset-thumbnail-signed-url \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"assetId\":\"assetId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let asset_id = env::var(\"OCTOSPARK_ASSET_ID\").unwrap_or_else(|_| \"assetId\".to_string());\n let url = format!(\"{}/v1/teams/{}/assets/{}/thumbnail-url\", base_url.trim_end_matches('/'), team_id, asset_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final assetId = Platform.environment['OCTOSPARK_ASSET_ID'] ?? 'assetId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/assets/$assetId/thumbnail-url';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Asset thumbnail signed URL", "x-displayName": "Asset thumbnail signed URL" } }, "/v1/teams/{teamId}/assets/{assetId}/url": { "get": { "tags": [ "Assets" ], "operationId": "assets.getAssetSignedUrl", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "assetId", "in": "path", "schema": { "type": "string", "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." }, "required": true, "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Get a temporary signed URL to download the original asset after checking access. This read is free. Request a new URL when an earlier one expires.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.getAssetSignedUrl({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n assetId: process.env.OCTOSPARK_ASSET_ID ?? \"assetId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.get_asset_signed_url(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n assetId=os.environ.get(\"OCTOSPARK_ASSET_ID\", \"assetId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets get-asset-signed-url \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"assetId\":\"assetId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let asset_id = env::var(\"OCTOSPARK_ASSET_ID\").unwrap_or_else(|_| \"assetId\".to_string());\n let url = format!(\"{}/v1/teams/{}/assets/{}/url\", base_url.trim_end_matches('/'), team_id, asset_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final assetId = Platform.environment['OCTOSPARK_ASSET_ID'] ?? 'assetId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/assets/$assetId/url';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Asset signed URL", "x-displayName": "Asset signed URL" } }, "/v1/teams/{teamId}/assets/agentic-search": { "post": { "tags": [ "Assets" ], "operationId": "assets.searchAgenticAssets", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor", "mode", "costResult", "embeddingStatus" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "source", "score", "rankingReasons", "asset", "assetUrl", "thumbnailUrl" ], "properties": { "source": { "type": "string", "enum": [ "team", "seed_library" ] }, "score": { "type": "number" }, "rankingReasons": { "type": "array", "items": { "type": "string" } }, "asset": { "type": "object", "required": [ "id", "teamId", "originalFilename", "fileSize", "mimeType", "assetType", "assetCategory", "assetTypeData", "storagePath", "thumbnailPath", "aiTitle", "aiDescription", "aiAltText", "aiTags", "contentHash", "processingStatus", "processingError", "isDeleted", "deletedAt", "hardDeletedAt", "sharedWithOrg", "folderId", "folderName", "displayName", "aspectRatio", "isProcessing", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "originalFilename": { "type": "string" }, "fileSize": { "type": "number" }, "mimeType": { "type": "string" }, "assetType": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ] }, "assetCategory": { "type": "string", "enum": [ "user_upload", "render", "template", "green_screen_template", "sound_effect", "music", "brand_asset", "ai_image", "ai_video", "other" ] }, "assetTypeData": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "type", "width", "height", "format" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "format": { "type": "string" }, "colorSpace": { "type": "string" }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "video" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "duration": { "type": "number" }, "codec": { "type": "string" }, "bitrate": { "type": "number" }, "fps": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "audio" ] }, "duration": { "type": "number" }, "sampleRate": { "type": "number" }, "channels": { "type": "number" }, "codec": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "frameCount" ], "properties": { "type": { "type": "string", "enum": [ "gif" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "frameCount": { "type": "number" }, "duration": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "format" ], "properties": { "type": { "type": "string", "enum": [ "document" ] }, "pageCount": { "type": "number" }, "format": { "type": "string" } }, "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "chromaKey", "analysisVersion", "confidence", "chromaKeyProfiles", "subjectAnalysis", "aspectRatioProfiles", "captioning", "audio", "composition" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "green_screen_template" ] }, "chromaKey": { "type": "object", "required": [ "keyColor", "ffmpegSimilarity", "ffmpegBlend", "spillRisk" ], "properties": { "keyColor": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}$", "pattern": "^#[0-9a-fA-F]{6}$" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" }, "spillRisk": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "additionalProperties": false }, "analysisVersion": { "type": "number" }, "confidence": { "type": "number" }, "chromaKeyProfiles": { "type": "object", "required": [ "baseline", "fallback" ], "properties": { "baseline": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "fallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "confidence": { "type": "number" }, "strongFallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "subjectAnalysis": { "type": "object", "required": [ "sampleCount", "sampleTimestampsSeconds", "representativeBounds", "subjectHeightFraction", "subjectWidthFraction", "centerXFraction", "bottomYFraction", "cropRisk", "faceRegion", "confidence" ], "properties": { "sampleCount": { "type": "number" }, "sampleTimestampsSeconds": { "type": "array", "items": { "type": "number" } }, "representativeBounds": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "defaultSubjectBounds": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "subjectHeightFraction": { "type": "number" }, "subjectWidthFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "bottomYFraction": { "type": "number" }, "cropRisk": { "type": "object", "required": [ "top", "bottom", "left", "right" ], "properties": { "top": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" }, "right": { "type": "number" } }, "additionalProperties": false }, "defaultFaceRegion": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRange": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRangeDelta": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "additionalProperties": false }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegion": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "confidence": { "type": "number" } }, "additionalProperties": false }, "aspectRatioProfiles": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "captioning": { "type": "object", "required": [ "preferredCaptionZones", "forbiddenCaptionZones", "subjectBoundsByAspectRatio", "faceRegionByAspectRatio", "captionSafeBandsByAspectRatio", "preferredZonesByAspectRatio", "forbiddenZonesByAspectRatio" ], "properties": { "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "16:9": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "1:1": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "4:5": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false }, "preferredZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "forbiddenZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "audio": { "type": "object", "required": [ "hasAudio", "likelyHasMusic", "likelyHasSpeech", "needsMusic" ], "properties": { "hasAudio": { "type": "boolean" }, "likelyHasMusic": { "type": "boolean" }, "likelyHasSpeech": { "type": "boolean" }, "needsMusic": { "type": "boolean" } }, "additionalProperties": false }, "composition": { "type": "object", "required": [ "safeCaptionZones", "captionSafeBandsByAspectRatio", "recommendedBackgroundTags", "recommendedMusicTags", "recommendedSoundEffectTags" ], "properties": { "safeCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "recommendedBackgroundTags": { "type": "array", "items": { "type": "string" } }, "recommendedMusicTags": { "type": "array", "items": { "type": "string" } }, "recommendedSoundEffectTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "aspectRatioCategory" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "background" ] }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatioCategory": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "other" ] }, "dominantColors": { "type": "array", "items": { "type": "string" } }, "isLoopable": { "type": "boolean" }, "textSafeZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "mood", "energyLevel" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "music" ] }, "mood": { "type": "array", "items": { "type": "string" } }, "energyLevel": { "type": "string", "enum": [ "low", "medium", "high", "variable" ] }, "tempo": { "type": "string", "enum": [ "slow", "medium", "fast", "variable" ] }, "hasVocals": { "type": "boolean" }, "isLoopable": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "effectCategory", "intensity", "timingUse" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "sound_effect" ] }, "effectCategory": { "type": "string" }, "intensity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "timingUse": { "type": "string", "enum": [ "intro", "impact", "reaction", "transition", "outro" ] } }, "additionalProperties": false } ] } ] }, { "type": "null" } ] }, "storagePath": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiAltText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTags": { "type": "array", "items": { "type": "string" } }, "contentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "processingError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDeleted": { "type": "boolean" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hardDeletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sharedWithOrg": { "type": "boolean" }, "folderId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "folderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "type": "string" }, "aspectRatio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isProcessing": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, "assetUrl": { "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "metadata", "semantic", "hybrid" ] }, "costResult": { "type": "object", "required": [ "name", "costInCreditsDecimillicents", "costInDollars", "marginCostInCreditsDecimillicents", "marginCostInDollars" ], "properties": { "name": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "costInCreditsDecimillicents": { "type": "number" }, "costInDollars": { "type": "number" }, "marginCostInCreditsDecimillicents": { "type": "number" }, "marginCostInDollars": { "type": "number" } }, "additionalProperties": false }, "embeddingStatus": { "anyOf": [ { "type": "object", "required": [ "embeddingsReady", "totalAssets", "withEmbeddings", "withoutEmbeddings", "message" ], "properties": { "embeddingsReady": { "type": "boolean" }, "totalAssets": { "type": "number" }, "withEmbeddings": { "type": "number" }, "withoutEmbeddings": { "type": "number" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Natural-language search over a team's assets. The default metadata mode is free keyword scoring; semantic and hybrid modes run AI embeddings and report their cost in the response costResult. Use the simpler keyword searchAssets first when a literal text match will do.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Natural-language search query; may be empty only for explicitly filtered browse mode.", "title": "maxLength(512)", "examples": [ "green screen clip of someone pointing upward" ], "maxLength": 512 }, "browse": { "type": "boolean", "description": "Browse by asset types and categories without an embedding request; both filters are required." }, "cursor": { "type": "string", "description": "a string at most 2048 character(s) long", "title": "maxLength(2048)", "maxLength": 2048 }, "requiredTags": { "type": "array", "items": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "description": "Exact tags that every browse result must contain, for example image_meme or category:animals. Available only with browse=true.", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "mode": { "type": "string", "enum": [ "metadata", "semantic", "hybrid" ], "description": "Search strategy: metadata (keyword scoring), semantic (vector embeddings), or hybrid (both); defaults to metadata.", "default": "metadata", "examples": [ "hybrid" ] }, "limit": { "type": "integer", "description": "Maximum number of results to return, 1 to 100; defaults to 10.", "title": "lessThanOrEqualTo(100)", "minimum": 1, "default": 10, "examples": [ 10 ], "maximum": 100 }, "includeSeedLibrary": { "type": "boolean", "description": "Whether to also search the shared Octospark seed template library alongside team assets." }, "assetTypes": { "type": "array", "items": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ] }, "description": "Restrict results to these asset types (image, video, audio, gif, document).", "examples": [ [ "image", "video" ] ] }, "assetCategories": { "type": "array", "items": { "type": "string", "enum": [ "user_upload", "render", "template", "green_screen_template", "sound_effect", "music", "brand_asset", "ai_image", "ai_video", "other" ] }, "description": "Restrict results to these asset categories, e.g. user_upload, render, green_screen_template, music.", "examples": [ [ "user_upload" ] ] } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.searchAgenticAssets({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.search_agentic_assets(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets semantic-search \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/assets/agentic-search\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/assets/agentic-search';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Search agentic assets", "x-displayName": "Search agentic assets" } }, "/v1/teams/{teamId}/assets/import": { "post": { "tags": [ "Assets" ], "operationId": "assets.importAsset", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "deduplicated" ], "properties": { "asset": { "type": "object", "required": [ "id", "teamId", "originalFilename", "fileSize", "mimeType", "assetType", "assetCategory", "assetTypeData", "storagePath", "thumbnailPath", "aiTitle", "aiDescription", "aiAltText", "aiTags", "contentHash", "processingStatus", "processingError", "isDeleted", "deletedAt", "hardDeletedAt", "sharedWithOrg", "folderId", "folderName", "displayName", "aspectRatio", "isProcessing", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "originalFilename": { "type": "string" }, "fileSize": { "type": "number" }, "mimeType": { "type": "string" }, "assetType": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ] }, "assetCategory": { "type": "string", "enum": [ "user_upload", "render", "template", "green_screen_template", "sound_effect", "music", "brand_asset", "ai_image", "ai_video", "other" ] }, "assetTypeData": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "type", "width", "height", "format" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "format": { "type": "string" }, "colorSpace": { "type": "string" }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "video" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "duration": { "type": "number" }, "codec": { "type": "string" }, "bitrate": { "type": "number" }, "fps": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "audio" ] }, "duration": { "type": "number" }, "sampleRate": { "type": "number" }, "channels": { "type": "number" }, "codec": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "frameCount" ], "properties": { "type": { "type": "string", "enum": [ "gif" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "frameCount": { "type": "number" }, "duration": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "format" ], "properties": { "type": { "type": "string", "enum": [ "document" ] }, "pageCount": { "type": "number" }, "format": { "type": "string" } }, "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "chromaKey", "analysisVersion", "confidence", "chromaKeyProfiles", "subjectAnalysis", "aspectRatioProfiles", "captioning", "audio", "composition" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "green_screen_template" ] }, "chromaKey": { "type": "object", "required": [ "keyColor", "ffmpegSimilarity", "ffmpegBlend", "spillRisk" ], "properties": { "keyColor": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}$", "pattern": "^#[0-9a-fA-F]{6}$" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" }, "spillRisk": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "additionalProperties": false }, "analysisVersion": { "type": "number" }, "confidence": { "type": "number" }, "chromaKeyProfiles": { "type": "object", "required": [ "baseline", "fallback" ], "properties": { "baseline": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "fallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "confidence": { "type": "number" }, "strongFallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "subjectAnalysis": { "type": "object", "required": [ "sampleCount", "sampleTimestampsSeconds", "representativeBounds", "subjectHeightFraction", "subjectWidthFraction", "centerXFraction", "bottomYFraction", "cropRisk", "faceRegion", "confidence" ], "properties": { "sampleCount": { "type": "number" }, "sampleTimestampsSeconds": { "type": "array", "items": { "type": "number" } }, "representativeBounds": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "defaultSubjectBounds": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "subjectHeightFraction": { "type": "number" }, "subjectWidthFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "bottomYFraction": { "type": "number" }, "cropRisk": { "type": "object", "required": [ "top", "bottom", "left", "right" ], "properties": { "top": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" }, "right": { "type": "number" } }, "additionalProperties": false }, "defaultFaceRegion": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRange": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRangeDelta": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "additionalProperties": false }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegion": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "confidence": { "type": "number" } }, "additionalProperties": false }, "aspectRatioProfiles": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "captioning": { "type": "object", "required": [ "preferredCaptionZones", "forbiddenCaptionZones", "subjectBoundsByAspectRatio", "faceRegionByAspectRatio", "captionSafeBandsByAspectRatio", "preferredZonesByAspectRatio", "forbiddenZonesByAspectRatio" ], "properties": { "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "16:9": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "1:1": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "4:5": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false }, "preferredZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "forbiddenZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "audio": { "type": "object", "required": [ "hasAudio", "likelyHasMusic", "likelyHasSpeech", "needsMusic" ], "properties": { "hasAudio": { "type": "boolean" }, "likelyHasMusic": { "type": "boolean" }, "likelyHasSpeech": { "type": "boolean" }, "needsMusic": { "type": "boolean" } }, "additionalProperties": false }, "composition": { "type": "object", "required": [ "safeCaptionZones", "captionSafeBandsByAspectRatio", "recommendedBackgroundTags", "recommendedMusicTags", "recommendedSoundEffectTags" ], "properties": { "safeCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "recommendedBackgroundTags": { "type": "array", "items": { "type": "string" } }, "recommendedMusicTags": { "type": "array", "items": { "type": "string" } }, "recommendedSoundEffectTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "aspectRatioCategory" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "background" ] }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatioCategory": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "other" ] }, "dominantColors": { "type": "array", "items": { "type": "string" } }, "isLoopable": { "type": "boolean" }, "textSafeZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "mood", "energyLevel" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "music" ] }, "mood": { "type": "array", "items": { "type": "string" } }, "energyLevel": { "type": "string", "enum": [ "low", "medium", "high", "variable" ] }, "tempo": { "type": "string", "enum": [ "slow", "medium", "fast", "variable" ] }, "hasVocals": { "type": "boolean" }, "isLoopable": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "effectCategory", "intensity", "timingUse" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "sound_effect" ] }, "effectCategory": { "type": "string" }, "intensity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "timingUse": { "type": "string", "enum": [ "intro", "impact", "reaction", "transition", "outro" ] } }, "additionalProperties": false } ] } ] }, { "type": "null" } ] }, "storagePath": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiAltText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTags": { "type": "array", "items": { "type": "string" } }, "contentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "processingError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDeleted": { "type": "boolean" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hardDeletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sharedWithOrg": { "type": "boolean" }, "folderId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "folderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "type": "string" }, "aspectRatio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isProcessing": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, "deduplicated": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Import an asset in a single call, either from a remote sourceUrl (fetched server-side) or from inline contentBase64 (max 10MB decoded). Returns the created asset; thumbnailing and enrichment run asynchronously. For large or local files, use the presigned requestUpload/confirmUpload flow instead so the bytes go directly to storage.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "sourceUrl": { "type": "string", "description": "Public http(s) URL the server fetches the file from (SSRF-guarded, max 200 MB); mutually exclusive with contentBase64.", "title": "minLength(1)", "examples": [ "https://example.com/media/launch-teaser.png" ], "minLength": 1 }, "contentBase64": { "type": "string", "description": "Base64-encoded file content for small payloads, max 10 MB decoded; mutually exclusive with sourceUrl, and requires fileName and mimeType.", "title": "minLength(1)", "examples": [ "iVBORw0KGgoAAAANSUhEUg..." ], "minLength": 1 }, "fileName": { "type": "string", "description": "Filename to store the asset under, including extension; required with contentBase64, otherwise derived from sourceUrl.", "title": "minLength(1)", "examples": [ "launch-teaser.png" ], "minLength": 1 }, "mimeType": { "type": "string", "description": "MIME type of the imported content; required with contentBase64, otherwise inferred from the fetch response.", "title": "minLength(1)", "examples": [ "image/png" ], "minLength": 1 }, "folderId": { "type": "string", "description": "Folder to place the newly imported asset in; must exist and belong to the team. Omit to land the asset at the team root.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.importAsset({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.import_asset(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets import-asset \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/assets/import\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/assets/import';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Import asset", "x-displayName": "Import asset" } }, "/v1/teams/{teamId}/assets/move": { "post": { "tags": [ "Assets" ], "operationId": "assets.moveAssets", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "movedCount" ], "properties": { "movedCount": { "type": "number" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Move a batch of assets into a folder in one call (pass folderId: null to move them to the library root). Returns the moved count. Use this for bulk reorganization instead of updating assets one at a time.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds", "folderId" ], "properties": { "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "minItems": 1, "maxItems": 100 }, "folderId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ], "description": "Destination folder id; null moves the assets to the root of the media library." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.moveAssets({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.move_assets(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets move-assets \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/assets/move\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/assets/move';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Move assets", "x-displayName": "Move assets" } }, "/v1/teams/{teamId}/assets/search": { "get": { "tags": [ "Assets" ], "operationId": "assets.searchAssets", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "query", "in": "query", "schema": { "type": "string", "description": "Keyword search query matched against asset names, tags, and AI-derived metadata.", "title": "minLength(1)", "examples": [ "product launch banner" ], "minLength": 1 }, "required": true, "description": "Keyword search query matched against asset names, tags, and AI-derived metadata." }, { "name": "semantic", "in": "query", "schema": { "type": "string", "description": "Reserved for a future semantic mode: any truthy value currently returns 400 (semantic search via this endpoint is not yet available). Omit it, and use searchAgenticAssets for natural-language search.", "examples": [ "false" ] }, "required": false, "description": "Reserved for a future semantic mode: any truthy value currently returns 400 (semantic search via this endpoint is not yet available). Omit it, and use searchAgenticAssets for natural-language search." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, "required": false, "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "Page size as a positive integer string; defaults to 25, capped at 100.", "default": "25", "examples": [ "25", "100" ] }, "required": false, "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt.", "examples": [ "createdAt" ] }, "required": false, "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt." }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc or desc; defaults to desc.", "default": "desc" }, "required": false, "description": "Sort direction: asc or desc; defaults to desc." }, { "name": "filter[assetType]", "in": "query", "schema": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ], "description": "Restrict results to one media type (e.g. image or video)." }, "required": false, "description": "Restrict results to one media type (e.g. image or video)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "originalFilename", "fileSize", "mimeType", "assetType", "assetCategory", "assetTypeData", "storagePath", "thumbnailPath", "aiTitle", "aiDescription", "aiAltText", "aiTags", "contentHash", "processingStatus", "processingError", "isDeleted", "deletedAt", "hardDeletedAt", "sharedWithOrg", "folderId", "folderName", "displayName", "aspectRatio", "isProcessing", "createdAt", "updatedAt", "thumbnailUrl", "fileUrl", "previewUrlsExpireAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "originalFilename": { "type": "string" }, "fileSize": { "type": "number" }, "mimeType": { "type": "string" }, "assetType": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ] }, "assetCategory": { "type": "string", "enum": [ "user_upload", "render", "template", "green_screen_template", "sound_effect", "music", "brand_asset", "ai_image", "ai_video", "other" ] }, "assetTypeData": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "type", "width", "height", "format" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "format": { "type": "string" }, "colorSpace": { "type": "string" }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "video" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "duration": { "type": "number" }, "codec": { "type": "string" }, "bitrate": { "type": "number" }, "fps": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "audio" ] }, "duration": { "type": "number" }, "sampleRate": { "type": "number" }, "channels": { "type": "number" }, "codec": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "frameCount" ], "properties": { "type": { "type": "string", "enum": [ "gif" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "frameCount": { "type": "number" }, "duration": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "format" ], "properties": { "type": { "type": "string", "enum": [ "document" ] }, "pageCount": { "type": "number" }, "format": { "type": "string" } }, "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "chromaKey", "analysisVersion", "confidence", "chromaKeyProfiles", "subjectAnalysis", "aspectRatioProfiles", "captioning", "audio", "composition" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "green_screen_template" ] }, "chromaKey": { "type": "object", "required": [ "keyColor", "ffmpegSimilarity", "ffmpegBlend", "spillRisk" ], "properties": { "keyColor": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}$", "pattern": "^#[0-9a-fA-F]{6}$" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" }, "spillRisk": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "additionalProperties": false }, "analysisVersion": { "type": "number" }, "confidence": { "type": "number" }, "chromaKeyProfiles": { "type": "object", "required": [ "baseline", "fallback" ], "properties": { "baseline": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "fallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "confidence": { "type": "number" }, "strongFallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "subjectAnalysis": { "type": "object", "required": [ "sampleCount", "sampleTimestampsSeconds", "representativeBounds", "subjectHeightFraction", "subjectWidthFraction", "centerXFraction", "bottomYFraction", "cropRisk", "faceRegion", "confidence" ], "properties": { "sampleCount": { "type": "number" }, "sampleTimestampsSeconds": { "type": "array", "items": { "type": "number" } }, "representativeBounds": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "defaultSubjectBounds": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "subjectHeightFraction": { "type": "number" }, "subjectWidthFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "bottomYFraction": { "type": "number" }, "cropRisk": { "type": "object", "required": [ "top", "bottom", "left", "right" ], "properties": { "top": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" }, "right": { "type": "number" } }, "additionalProperties": false }, "defaultFaceRegion": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRange": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRangeDelta": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "additionalProperties": false }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegion": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "confidence": { "type": "number" } }, "additionalProperties": false }, "aspectRatioProfiles": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "captioning": { "type": "object", "required": [ "preferredCaptionZones", "forbiddenCaptionZones", "subjectBoundsByAspectRatio", "faceRegionByAspectRatio", "captionSafeBandsByAspectRatio", "preferredZonesByAspectRatio", "forbiddenZonesByAspectRatio" ], "properties": { "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "16:9": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "1:1": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "4:5": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false }, "preferredZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "forbiddenZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "audio": { "type": "object", "required": [ "hasAudio", "likelyHasMusic", "likelyHasSpeech", "needsMusic" ], "properties": { "hasAudio": { "type": "boolean" }, "likelyHasMusic": { "type": "boolean" }, "likelyHasSpeech": { "type": "boolean" }, "needsMusic": { "type": "boolean" } }, "additionalProperties": false }, "composition": { "type": "object", "required": [ "safeCaptionZones", "captionSafeBandsByAspectRatio", "recommendedBackgroundTags", "recommendedMusicTags", "recommendedSoundEffectTags" ], "properties": { "safeCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "recommendedBackgroundTags": { "type": "array", "items": { "type": "string" } }, "recommendedMusicTags": { "type": "array", "items": { "type": "string" } }, "recommendedSoundEffectTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "aspectRatioCategory" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "background" ] }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatioCategory": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "other" ] }, "dominantColors": { "type": "array", "items": { "type": "string" } }, "isLoopable": { "type": "boolean" }, "textSafeZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "mood", "energyLevel" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "music" ] }, "mood": { "type": "array", "items": { "type": "string" } }, "energyLevel": { "type": "string", "enum": [ "low", "medium", "high", "variable" ] }, "tempo": { "type": "string", "enum": [ "slow", "medium", "fast", "variable" ] }, "hasVocals": { "type": "boolean" }, "isLoopable": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "effectCategory", "intensity", "timingUse" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "sound_effect" ] }, "effectCategory": { "type": "string" }, "intensity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "timingUse": { "type": "string", "enum": [ "intro", "impact", "reaction", "transition", "outro" ] } }, "additionalProperties": false } ] } ] }, { "type": "null" } ] }, "storagePath": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiAltText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTags": { "type": "array", "items": { "type": "string" } }, "contentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "processingError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDeleted": { "type": "boolean" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hardDeletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sharedWithOrg": { "type": "boolean" }, "folderId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "folderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "type": "string" }, "aspectRatio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isProcessing": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Signed URL of the generated thumbnail, or null when the asset has none." }, "fileUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Signed URL of the original file, included only for images and videos without a thumbnail (the preview renders the original instead). Null otherwise; use getAssetSignedUrl for full-size access." }, "previewUrlsExpireAt": { "type": "string", "description": "ISO-8601 time when thumbnailUrl and fileUrl stop working. Refetch the list before this time rather than signing assets one by one." } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Keyword search over a team's active assets. Free: no credits are spent. Try this first; switch to searchAgenticAssets (natural-language search) only when a plain text match is not enough.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.searchAssets({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {\n \"query\": process.env.OCTOSPARK_QUERY ?? \"query\",\n },\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.search_assets(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n query={\n \"query\": os.environ.get(\"OCTOSPARK_QUERY\", \"query\"),\n }\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets search \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"query\":{\"query\":\"query\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let query = env::var(\"OCTOSPARK_QUERY\").unwrap_or_else(|_| \"query\".to_string());\n let url = format!(\"{}/v1/teams/{}/assets/search\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let query = [(\"query\", query.as_str())];\n request = request.query(&query);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final query = Platform.environment['OCTOSPARK_QUERY'] ?? 'query';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/assets/search';\n final uri = Uri.parse(url).replace(queryParameters: {\n 'query': query,\n });\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Search assets", "x-displayName": "Search assets" } }, "/v1/teams/{teamId}/assets/trash": { "get": { "tags": [ "Assets" ], "operationId": "assets.listTrash", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, "required": false, "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "Page size as a positive integer string; defaults to 25, capped at 100.", "default": "25", "examples": [ "25", "100" ] }, "required": false, "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt.", "examples": [ "createdAt" ] }, "required": false, "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt." }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc or desc; defaults to desc.", "default": "desc" }, "required": false, "description": "Sort direction: asc or desc; defaults to desc." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "originalFilename", "fileSize", "mimeType", "assetType", "assetCategory", "assetTypeData", "storagePath", "thumbnailPath", "aiTitle", "aiDescription", "aiAltText", "aiTags", "contentHash", "processingStatus", "processingError", "isDeleted", "deletedAt", "hardDeletedAt", "sharedWithOrg", "folderId", "folderName", "displayName", "aspectRatio", "isProcessing", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "originalFilename": { "type": "string" }, "fileSize": { "type": "number" }, "mimeType": { "type": "string" }, "assetType": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ] }, "assetCategory": { "type": "string", "enum": [ "user_upload", "render", "template", "green_screen_template", "sound_effect", "music", "brand_asset", "ai_image", "ai_video", "other" ] }, "assetTypeData": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "type", "width", "height", "format" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "format": { "type": "string" }, "colorSpace": { "type": "string" }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "video" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "duration": { "type": "number" }, "codec": { "type": "string" }, "bitrate": { "type": "number" }, "fps": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "audio" ] }, "duration": { "type": "number" }, "sampleRate": { "type": "number" }, "channels": { "type": "number" }, "codec": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "frameCount" ], "properties": { "type": { "type": "string", "enum": [ "gif" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "frameCount": { "type": "number" }, "duration": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "format" ], "properties": { "type": { "type": "string", "enum": [ "document" ] }, "pageCount": { "type": "number" }, "format": { "type": "string" } }, "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "chromaKey", "analysisVersion", "confidence", "chromaKeyProfiles", "subjectAnalysis", "aspectRatioProfiles", "captioning", "audio", "composition" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "green_screen_template" ] }, "chromaKey": { "type": "object", "required": [ "keyColor", "ffmpegSimilarity", "ffmpegBlend", "spillRisk" ], "properties": { "keyColor": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}$", "pattern": "^#[0-9a-fA-F]{6}$" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" }, "spillRisk": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "additionalProperties": false }, "analysisVersion": { "type": "number" }, "confidence": { "type": "number" }, "chromaKeyProfiles": { "type": "object", "required": [ "baseline", "fallback" ], "properties": { "baseline": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "fallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "confidence": { "type": "number" }, "strongFallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "subjectAnalysis": { "type": "object", "required": [ "sampleCount", "sampleTimestampsSeconds", "representativeBounds", "subjectHeightFraction", "subjectWidthFraction", "centerXFraction", "bottomYFraction", "cropRisk", "faceRegion", "confidence" ], "properties": { "sampleCount": { "type": "number" }, "sampleTimestampsSeconds": { "type": "array", "items": { "type": "number" } }, "representativeBounds": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "defaultSubjectBounds": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "subjectHeightFraction": { "type": "number" }, "subjectWidthFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "bottomYFraction": { "type": "number" }, "cropRisk": { "type": "object", "required": [ "top", "bottom", "left", "right" ], "properties": { "top": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" }, "right": { "type": "number" } }, "additionalProperties": false }, "defaultFaceRegion": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRange": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRangeDelta": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "additionalProperties": false }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegion": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "confidence": { "type": "number" } }, "additionalProperties": false }, "aspectRatioProfiles": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "captioning": { "type": "object", "required": [ "preferredCaptionZones", "forbiddenCaptionZones", "subjectBoundsByAspectRatio", "faceRegionByAspectRatio", "captionSafeBandsByAspectRatio", "preferredZonesByAspectRatio", "forbiddenZonesByAspectRatio" ], "properties": { "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "16:9": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "1:1": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "4:5": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false }, "preferredZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "forbiddenZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "audio": { "type": "object", "required": [ "hasAudio", "likelyHasMusic", "likelyHasSpeech", "needsMusic" ], "properties": { "hasAudio": { "type": "boolean" }, "likelyHasMusic": { "type": "boolean" }, "likelyHasSpeech": { "type": "boolean" }, "needsMusic": { "type": "boolean" } }, "additionalProperties": false }, "composition": { "type": "object", "required": [ "safeCaptionZones", "captionSafeBandsByAspectRatio", "recommendedBackgroundTags", "recommendedMusicTags", "recommendedSoundEffectTags" ], "properties": { "safeCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "recommendedBackgroundTags": { "type": "array", "items": { "type": "string" } }, "recommendedMusicTags": { "type": "array", "items": { "type": "string" } }, "recommendedSoundEffectTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "aspectRatioCategory" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "background" ] }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatioCategory": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "other" ] }, "dominantColors": { "type": "array", "items": { "type": "string" } }, "isLoopable": { "type": "boolean" }, "textSafeZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "mood", "energyLevel" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "music" ] }, "mood": { "type": "array", "items": { "type": "string" } }, "energyLevel": { "type": "string", "enum": [ "low", "medium", "high", "variable" ] }, "tempo": { "type": "string", "enum": [ "slow", "medium", "fast", "variable" ] }, "hasVocals": { "type": "boolean" }, "isLoopable": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "effectCategory", "intensity", "timingUse" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "sound_effect" ] }, "effectCategory": { "type": "string" }, "intensity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "timingUse": { "type": "string", "enum": [ "intro", "impact", "reaction", "transition", "outro" ] } }, "additionalProperties": false } ] } ] }, { "type": "null" } ] }, "storagePath": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiAltText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTags": { "type": "array", "items": { "type": "string" } }, "contentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "processingError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDeleted": { "type": "boolean" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hardDeletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sharedWithOrg": { "type": "boolean" }, "folderId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "folderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "type": "string" }, "aspectRatio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isProcessing": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the soft-deleted assets in a team's trash. Trashed assets are excluded from listAssets and search; use restoreAsset with an id from this list to bring one back.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.listTrash({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.list_trash(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets list-trash \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/assets/trash\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/assets/trash';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List trash", "x-displayName": "List trash" } }, "/v1/teams/{teamId}/uploads/{uploadId}/confirm": { "post": { "tags": [ "Assets" ], "operationId": "assets.confirmUpload", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "uploadId", "in": "path", "schema": { "type": "string", "description": "Upload session id returned by the request-upload endpoint; confirm the upload with it after the bytes are PUT to the presigned URL." }, "required": true, "description": "Upload session id returned by the request-upload endpoint; confirm the upload with it after the bytes are PUT to the presigned URL." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "originalFilename", "fileSize", "mimeType", "assetType", "assetCategory", "assetTypeData", "storagePath", "thumbnailPath", "aiTitle", "aiDescription", "aiAltText", "aiTags", "contentHash", "processingStatus", "processingError", "isDeleted", "deletedAt", "hardDeletedAt", "sharedWithOrg", "folderId", "folderName", "displayName", "aspectRatio", "isProcessing", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "originalFilename": { "type": "string" }, "fileSize": { "type": "number" }, "mimeType": { "type": "string" }, "assetType": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ] }, "assetCategory": { "type": "string", "enum": [ "user_upload", "render", "template", "green_screen_template", "sound_effect", "music", "brand_asset", "ai_image", "ai_video", "other" ] }, "assetTypeData": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "type", "width", "height", "format" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "format": { "type": "string" }, "colorSpace": { "type": "string" }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "video" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "duration": { "type": "number" }, "codec": { "type": "string" }, "bitrate": { "type": "number" }, "fps": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "audio" ] }, "duration": { "type": "number" }, "sampleRate": { "type": "number" }, "channels": { "type": "number" }, "codec": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "frameCount" ], "properties": { "type": { "type": "string", "enum": [ "gif" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "frameCount": { "type": "number" }, "duration": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "format" ], "properties": { "type": { "type": "string", "enum": [ "document" ] }, "pageCount": { "type": "number" }, "format": { "type": "string" } }, "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "chromaKey", "analysisVersion", "confidence", "chromaKeyProfiles", "subjectAnalysis", "aspectRatioProfiles", "captioning", "audio", "composition" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "green_screen_template" ] }, "chromaKey": { "type": "object", "required": [ "keyColor", "ffmpegSimilarity", "ffmpegBlend", "spillRisk" ], "properties": { "keyColor": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}$", "pattern": "^#[0-9a-fA-F]{6}$" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" }, "spillRisk": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "additionalProperties": false }, "analysisVersion": { "type": "number" }, "confidence": { "type": "number" }, "chromaKeyProfiles": { "type": "object", "required": [ "baseline", "fallback" ], "properties": { "baseline": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "fallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "confidence": { "type": "number" }, "strongFallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "subjectAnalysis": { "type": "object", "required": [ "sampleCount", "sampleTimestampsSeconds", "representativeBounds", "subjectHeightFraction", "subjectWidthFraction", "centerXFraction", "bottomYFraction", "cropRisk", "faceRegion", "confidence" ], "properties": { "sampleCount": { "type": "number" }, "sampleTimestampsSeconds": { "type": "array", "items": { "type": "number" } }, "representativeBounds": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "defaultSubjectBounds": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "subjectHeightFraction": { "type": "number" }, "subjectWidthFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "bottomYFraction": { "type": "number" }, "cropRisk": { "type": "object", "required": [ "top", "bottom", "left", "right" ], "properties": { "top": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" }, "right": { "type": "number" } }, "additionalProperties": false }, "defaultFaceRegion": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRange": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRangeDelta": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "additionalProperties": false }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegion": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "confidence": { "type": "number" } }, "additionalProperties": false }, "aspectRatioProfiles": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "captioning": { "type": "object", "required": [ "preferredCaptionZones", "forbiddenCaptionZones", "subjectBoundsByAspectRatio", "faceRegionByAspectRatio", "captionSafeBandsByAspectRatio", "preferredZonesByAspectRatio", "forbiddenZonesByAspectRatio" ], "properties": { "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "16:9": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "1:1": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "4:5": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false }, "preferredZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "forbiddenZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "audio": { "type": "object", "required": [ "hasAudio", "likelyHasMusic", "likelyHasSpeech", "needsMusic" ], "properties": { "hasAudio": { "type": "boolean" }, "likelyHasMusic": { "type": "boolean" }, "likelyHasSpeech": { "type": "boolean" }, "needsMusic": { "type": "boolean" } }, "additionalProperties": false }, "composition": { "type": "object", "required": [ "safeCaptionZones", "captionSafeBandsByAspectRatio", "recommendedBackgroundTags", "recommendedMusicTags", "recommendedSoundEffectTags" ], "properties": { "safeCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "recommendedBackgroundTags": { "type": "array", "items": { "type": "string" } }, "recommendedMusicTags": { "type": "array", "items": { "type": "string" } }, "recommendedSoundEffectTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "aspectRatioCategory" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "background" ] }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatioCategory": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "other" ] }, "dominantColors": { "type": "array", "items": { "type": "string" } }, "isLoopable": { "type": "boolean" }, "textSafeZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "mood", "energyLevel" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "music" ] }, "mood": { "type": "array", "items": { "type": "string" } }, "energyLevel": { "type": "string", "enum": [ "low", "medium", "high", "variable" ] }, "tempo": { "type": "string", "enum": [ "slow", "medium", "fast", "variable" ] }, "hasVocals": { "type": "boolean" }, "isLoopable": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "effectCategory", "intensity", "timingUse" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "sound_effect" ] }, "effectCategory": { "type": "string" }, "intensity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "timingUse": { "type": "string", "enum": [ "intro", "impact", "reaction", "transition", "outro" ] } }, "additionalProperties": false } ] } ] }, { "type": "null" } ] }, "storagePath": { "type": "string" }, "thumbnailPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiAltText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiTags": { "type": "array", "items": { "type": "string" } }, "contentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processingStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "processingError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDeleted": { "type": "boolean" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hardDeletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sharedWithOrg": { "type": "boolean" }, "folderId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "folderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "type": "string" }, "aspectRatio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isProcessing": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Finalize a presigned upload started with requestUpload: verifies the uploaded object's size, creates the asset record, and kicks off thumbnailing and enrichment asynchronously. Call this only after the PUT to the presigned URL has completed. Returns the newly created asset.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.confirmUpload({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n uploadId: process.env.OCTOSPARK_UPLOAD_ID ?? \"uploadId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.confirm_upload(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n uploadId=os.environ.get(\"OCTOSPARK_UPLOAD_ID\", \"uploadId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets confirm-upload \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"uploadId\":\"uploadId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let upload_id = env::var(\"OCTOSPARK_UPLOAD_ID\").unwrap_or_else(|_| \"uploadId\".to_string());\n let url = format!(\"{}/v1/teams/{}/uploads/{}/confirm\", base_url.trim_end_matches('/'), team_id, upload_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final uploadId = Platform.environment['OCTOSPARK_UPLOAD_ID'] ?? 'uploadId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/uploads/$uploadId/confirm';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.post(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Confirm upload", "x-displayName": "Confirm upload" } }, "/v1/teams/{teamId}/uploads/request": { "post": { "tags": [ "Assets" ], "operationId": "assets.requestUpload", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "uploadId", "presignedUrl", "deduplicated", "existingAssetId" ], "properties": { "uploadId": { "$ref": "#/components/schemas/UUID" }, "presignedUrl": { "type": "string" }, "deduplicated": { "type": "boolean" }, "existingAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Begin the presigned upload flow for large or local files: returns an uploadId plus a presigned URL. PUT the raw file bytes to that URL, then call confirmUpload to create the asset; no asset exists until confirmation. For a remote URL or a small inline payload (up to 10MB decoded), importAsset is the simpler single-call alternative.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "fileName", "fileSize", "contentHash", "mimeType" ], "properties": { "fileName": { "type": "string", "description": "Original filename of the file to upload, including extension.", "title": "minLength(1)", "examples": [ "launch-teaser.mp4" ], "minLength": 1 }, "fileSize": { "type": "integer", "description": "Exact file size in bytes; max 200 MB (209715200 bytes) per asset.", "title": "greaterThanOrEqualTo(1)", "examples": [ 1048576 ], "minimum": 1 }, "contentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 hex digest of the file content, used for deduplication; null skips the dedupe check.", "examples": [ "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" ] }, "mimeType": { "type": "string", "description": "MIME type of the file content.", "title": "minLength(1)", "examples": [ "video/mp4", "image/png" ], "minLength": 1 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.assets.requestUpload({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.assets.request_upload(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark assets request-upload \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/uploads/request\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/uploads/request';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Request upload", "x-displayName": "Request upload" } }, "/v1/agent/context": { "get": { "tags": [ "Agent" ], "operationId": "agent.getContext", "parameters": [], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "user", "organizations", "teams", "defaultOrganizationId", "defaultTeamId" ], "properties": { "user": { "type": "object", "required": [ "id", "email" ], "properties": { "id": { "type": "string" }, "email": { "type": "string" } }, "additionalProperties": false }, "organizations": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "required": [ "id", "organizationId", "name" ], "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false } }, "defaultOrganizationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultTeamId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Return the authenticated caller's full working context in one call: user, organizations, teams, and default ids. Call this first in an agent session to resolve the teamId and organizationId that nearly every other endpoint requires. Read-only aggregation with no side effects.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.agent.getContext()" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.agent.get_context()" }, { "lang": "CLI", "label": "CLI", "source": "octospark context" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let url = format!(\"{}/v1/agent/context\", base_url.trim_end_matches('/'));\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/agent/context';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Get agent context", "x-displayName": "Get agent context" } }, "/v1/billing/{organizationId}/credits": { "get": { "tags": [ "Billing" ], "operationId": "billing.getCreditBalance", "parameters": [ { "name": "organizationId", "in": "path", "schema": { "type": "string", "description": "Organization id (UUID). Discover ids via the list organizations endpoint or the agent context." }, "required": true, "description": "Organization id (UUID). Discover ids via the list organizations endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "creditsBalanceDecimillicents", "reservedCreditsDecimillicents", "availableDecimillicents", "creditsBalanceDollars", "reservedCreditsDollars", "availableDollars", "isSuspended", "suspendedAt", "paymentGracePeriodEndsAt" ], "properties": { "creditsBalanceDecimillicents": { "type": "number", "description": "Total credit balance in decimillicents (10000000 = $1), including credits currently reserved by in-flight operations.", "examples": [ 200000000 ] }, "reservedCreditsDecimillicents": { "type": "number", "description": "Credits in decimillicents currently held by in-flight reservations (e.g. pending publishes or AI calls).", "examples": [ 20000 ] }, "availableDecimillicents": { "type": "number", "description": "Spendable credits in decimillicents: balance minus reserved.", "examples": [ 199980000 ] }, "creditsBalanceDollars": { "type": "number", "description": "creditsBalanceDecimillicents expressed in dollars (decimillicents / 10,000,000), for display without unit conversion.", "examples": [ 20 ] }, "reservedCreditsDollars": { "type": "number", "description": "reservedCreditsDecimillicents expressed in dollars.", "examples": [ 0.002 ] }, "availableDollars": { "type": "number", "description": "availableDecimillicents expressed in dollars: what the org can spend right now.", "examples": [ 19.998 ] }, "isSuspended": { "type": "boolean", "description": "True when the org is blocked from new credit-consuming operations: either suspended (usage cap exceeded, open dispute) or inside an unresolved failed-payment grace period." }, "suspendedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of when the org was suspended, or null when the org is healthy.", "examples": [ "2026-06-10T14:32:00Z" ] }, "paymentGracePeriodEndsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 end of the current failed-payment grace period, or null when there is no unresolved payment failure; only a successful payment clears it, wall-clock expiry does not unblock the org.", "examples": [ "2026-06-17T14:32:00Z" ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Get the organization's current credit balance. Every amount comes in two forms: precise decimillicents (10,000,000 = $1) and ready-to-display dollars, so you never have to convert. Check the available amount before paid operations like publishing or live analytics reads; if it runs out mid-publish, the failure shows up as per-account errors. For the itemized ledger behind the balance, use getCreditHistory.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.billing.getCreditBalance({\n organizationId: process.env.OCTOSPARK_ORGANIZATION_ID ?? \"organizationId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.billing.get_credit_balance(\n organizationId=os.environ.get(\"OCTOSPARK_ORGANIZATION_ID\", \"organizationId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark billing balance \\\n --request '{\"path\":{\"organizationId\":\"organizationId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let organization_id = env::var(\"OCTOSPARK_ORGANIZATION_ID\").unwrap_or_else(|_| \"organizationId\".to_string());\n let url = format!(\"{}/v1/billing/{}/credits\", base_url.trim_end_matches('/'), organization_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final organizationId = Platform.environment['OCTOSPARK_ORGANIZATION_ID'] ?? 'organizationId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/billing/$organizationId/credits';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Credit balance", "x-displayName": "Credit balance" } }, "/v1/billing/{organizationId}/credits/history": { "get": { "tags": [ "Billing" ], "operationId": "billing.getCreditHistory", "parameters": [ { "name": "organizationId", "in": "path", "schema": { "type": "string", "description": "Organization id (UUID). Discover ids via the list organizations endpoint or the agent context." }, "required": true, "description": "Organization id (UUID). Discover ids via the list organizations endpoint or the agent context." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, "required": false, "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "Page size as a positive integer string; defaults to 25, capped at 100.", "default": "25", "examples": [ "25", "100" ] }, "required": false, "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt.", "examples": [ "createdAt" ] }, "required": false, "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt." }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc or desc; defaults to desc.", "default": "desc" }, "required": false, "description": "Sort direction: asc or desc; defaults to desc." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "entryType", "amountDecimillicents", "reason", "referenceId", "balanceAfter", "createdAt" ], "properties": { "id": { "type": "string", "description": "UUID of the ledger entry.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "entryType": { "type": "string", "enum": [ "purchase", "usage", "adjustment", "refund", "auto_recharge", "reserve", "release" ], "description": "Kind of ledger movement: purchase, usage, adjustment, refund, auto_recharge, reserve, or release.", "examples": [ "purchase", "usage" ] }, "amountDecimillicents": { "type": "number", "description": "Signed amount of the movement in decimillicents (10000000 = $1); positive for credits added, negative for usage.", "examples": [ 200000000, -20000 ] }, "reason": { "type": "string", "description": "Human-readable explanation of the ledger movement.", "examples": [ "Credit top-up via Stripe Checkout" ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identifier of the related record (e.g. Stripe payment intent or usage record id), or null when there is none." }, "balanceAfter": { "type": "number", "description": "Credit balance in decimillicents immediately after this entry was applied.", "examples": [ 199980000 ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp of when the ledger entry was written.", "examples": [ "2026-06-11T09:15:00Z" ] } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the organization's credit ledger entries (grants, top-ups, deductions), with amounts in decimillicents (1/10,000 of a cent). Use this to audit where credits were spent; use getCreditBalance when you only need the current balance.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.billing.getCreditHistory({\n organizationId: process.env.OCTOSPARK_ORGANIZATION_ID ?? \"organizationId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.billing.get_credit_history(\n organizationId=os.environ.get(\"OCTOSPARK_ORGANIZATION_ID\", \"organizationId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark billing history \\\n --request '{\"path\":{\"organizationId\":\"organizationId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let organization_id = env::var(\"OCTOSPARK_ORGANIZATION_ID\").unwrap_or_else(|_| \"organizationId\".to_string());\n let url = format!(\"{}/v1/billing/{}/credits/history\", base_url.trim_end_matches('/'), organization_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final organizationId = Platform.environment['OCTOSPARK_ORGANIZATION_ID'] ?? 'organizationId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/billing/$organizationId/credits/history';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Credit history", "x-displayName": "Credit history" } }, "/v1/billing/{organizationId}/top-up": { "post": { "tags": [ "Billing" ], "operationId": "billing.createTopUpSession", "parameters": [ { "name": "organizationId", "in": "path", "schema": { "type": "string", "description": "Organization id (UUID). Discover ids via the list organizations endpoint or the agent context." }, "required": true, "description": "Organization id (UUID). Discover ids via the list organizations endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "url" ], "properties": { "id": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create a Stripe checkout session for a one-off credit top-up and return the session URL for a human to complete payment in a browser. No charge happens on this call; credits are granted only after Stripe confirms payment. Check getCreditBalance first to see whether a top-up is actually needed.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "amountDecimillicents", "successUrl", "cancelUrl" ], "properties": { "amountDecimillicents": { "type": "integer", "description": "One-time credit purchase amount in decimillicents (10000000 decimillicents = $1, so 100000 = 1 cent); min 5000000 ($0.50, the Stripe minimum charge), max 5000000000 ($500).", "title": "lessThanOrEqualTo(5000000000)", "minimum": 5000000, "examples": [ 200000000 ], "maximum": 5000000000 }, "successUrl": { "type": "string", "description": "http(s) URL Stripe redirects the user to after a successful checkout.", "examples": [ "https://app.octospark.ai/billing?topup=success" ], "pattern": "^https?:\\/\\/" }, "cancelUrl": { "type": "string", "description": "http(s) URL Stripe redirects the user to when they abandon the checkout.", "examples": [ "https://app.octospark.ai/billing?topup=cancelled" ], "pattern": "^https?:\\/\\/" } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.billing.createTopUpSession({\n organizationId: process.env.OCTOSPARK_ORGANIZATION_ID ?? \"organizationId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.billing.create_top_up_session(\n organizationId=os.environ.get(\"OCTOSPARK_ORGANIZATION_ID\", \"organizationId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark billing topup \\\n --request '{\"path\":{\"organizationId\":\"organizationId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let organization_id = env::var(\"OCTOSPARK_ORGANIZATION_ID\").unwrap_or_else(|_| \"organizationId\".to_string());\n let url = format!(\"{}/v1/billing/{}/top-up\", base_url.trim_end_matches('/'), organization_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final organizationId = Platform.environment['OCTOSPARK_ORGANIZATION_ID'] ?? 'organizationId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/billing/$organizationId/top-up';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create top up session", "x-displayName": "Create top up session" } }, "/v1/teams/{teamId}/ai-media/models": { "get": { "tags": [ "Media generation" ], "operationId": "ai-media.listModels", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "modality", "in": "query", "schema": { "type": "string", "enum": [ "image", "video" ], "description": "Return only models for this modality (image or video)." }, "required": false, "description": "Return only models for this modality (image or video)." }, { "name": "provider", "in": "query", "schema": { "type": "string", "enum": [ "google", "openai", "bytedance", "kuaishou", "alibaba", "minimax", "blackforestlabs", "openrouter", "fal", "xai", "runway", "recraft", "krea" ], "description": "Return only models from this provider (for example the code for OpenAI, Google, or fal.ai)." }, "required": false, "description": "Return only models from this provider (for example the code for OpenAI, Google, or fal.ai)." }, { "name": "route", "in": "query", "schema": { "type": "string", "enum": [ "openrouter", "fal" ], "description": "Return only models reachable over this route (for example openrouter or a direct provider route)." }, "required": false, "description": "Return only models reachable over this route (for example openrouter or a direct provider route)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "modality", "route", "routingProviderCode", "modelOwnerProviderCode", "providerModelId", "capabilitySchemaVersion", "capabilities", "defaultParams", "pricingSource", "enabled", "lifecycle" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "isNew": { "type": "boolean" }, "modality": { "type": "string", "enum": [ "image", "video" ] }, "route": { "type": "string", "enum": [ "openrouter", "fal" ] }, "routingProviderCode": { "type": "string", "enum": [ "google", "openai", "bytedance", "kuaishou", "alibaba", "minimax", "blackforestlabs", "openrouter", "fal", "xai", "runway", "recraft", "krea" ] }, "modelOwnerProviderCode": { "type": "string", "enum": [ "google", "openai", "bytedance", "kuaishou", "alibaba", "minimax", "blackforestlabs", "openrouter", "fal", "xai", "runway", "recraft", "krea" ] }, "providerModelId": { "type": "string" }, "providerEndpointId": { "type": "string" }, "capabilitySchemaVersion": { "type": "string" }, "capabilities": { "anyOf": [ { "type": "object", "required": [ "modality", "aspectRatios", "counts", "referenceImages", "allowedPassthroughParameters", "paramsSchemaId", "uiSchemaId" ], "properties": { "modality": { "type": "string", "enum": [ "image" ] }, "aspectRatios": { "type": "array", "items": { "type": "string", "enum": [ "1:1", "4:5", "9:16", "16:9", "3:2", "2:3", "4:3", "3:4" ] } }, "resolutions": { "type": "array", "items": { "type": "string", "enum": [ "512", "1K", "2K", "4K" ] } }, "qualities": { "type": "array", "items": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "sizes": { "type": "array", "items": { "type": "string" } }, "counts": { "type": "object", "required": [ "min", "max" ], "properties": { "min": { "type": "number" }, "max": { "type": "number" } }, "additionalProperties": false }, "referenceImages": { "type": "object", "required": [ "arity" ], "properties": { "arity": { "type": "string", "enum": [ "none", "single", "multi" ] }, "min": { "type": "number" }, "max": { "type": "number" } }, "additionalProperties": false }, "seed": { "type": "object", "required": [ "supported" ], "properties": { "supported": { "type": "boolean" }, "default": { "type": "boolean" } }, "additionalProperties": false }, "negativePrompt": { "type": "object", "required": [ "supported" ], "properties": { "supported": { "type": "boolean" }, "default": { "type": "boolean" } }, "additionalProperties": false }, "allowedPassthroughParameters": { "type": "array", "items": { "type": "string" } }, "paramsSchemaId": { "type": "string", "enum": [ "image.core.v1", "video.core.v1" ] }, "uiSchemaId": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "modality", "aspectRatios", "resolutions", "durationsSeconds", "referenceImages", "audio", "allowedPassthroughParameters", "paramsSchemaId", "uiSchemaId", "requiresEnrichmentBeforeAgentUse" ], "properties": { "modality": { "type": "string", "enum": [ "video" ] }, "aspectRatios": { "type": "array", "items": { "type": "string", "enum": [ "1:1", "4:5", "9:16", "16:9", "3:2", "2:3", "4:3", "3:4" ] } }, "resolutions": { "type": "array", "items": { "type": "string", "enum": [ "480p", "720p", "768p", "1080p", "2K" ] } }, "durationsSeconds": { "type": "array", "items": { "type": "number" } }, "referenceImages": { "type": "object", "required": [ "arity" ], "properties": { "arity": { "type": "string", "enum": [ "none", "single", "multi" ] }, "min": { "type": "number" }, "max": { "type": "number" } }, "additionalProperties": false }, "audio": { "type": "object", "required": [ "supported", "default" ], "properties": { "supported": { "type": "boolean" }, "default": { "type": "boolean" } }, "additionalProperties": false }, "seed": { "type": "object", "required": [ "supported" ], "properties": { "supported": { "type": "boolean" }, "default": { "type": "boolean" } }, "additionalProperties": false }, "negativePrompt": { "type": "object", "required": [ "supported" ], "properties": { "supported": { "type": "boolean" }, "default": { "type": "boolean" } }, "additionalProperties": false }, "allowedPassthroughParameters": { "type": "array", "items": { "type": "string" } }, "paramsSchemaId": { "type": "string", "enum": [ "image.core.v1", "video.core.v1" ] }, "uiSchemaId": { "type": "string" }, "requiresEnrichmentBeforeAgentUse": { "type": "boolean", "enum": [ true ] } }, "additionalProperties": false } ] }, "defaultParams": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "pricingSource": { "type": "string", "enum": [ "openrouter_usage", "provider_snapshot" ] }, "enabled": { "type": "boolean" }, "lifecycle": { "type": "string", "enum": [ "active", "deprecated", "retired" ] }, "replacedByModelId": { "type": "string" }, "retiredAt": { "type": "string" }, "listPrice": { "type": "object", "required": [ "unit", "unitPriceUsd", "pricingVerifiedAt", "stale" ], "properties": { "unit": { "type": "string", "description": "Billing unit the rate is quoted in: per_image or per_video_second." }, "unitPriceUsd": { "type": "number", "description": "Customer-facing price in USD per unit, margin already applied." }, "pricingVerifiedAt": { "type": "string", "description": "ISO-8601 instant the underlying pricing snapshot was last verified." }, "stale": { "type": "boolean", "description": "True when the snapshot is past the freshness limit; paid generation is blocked while stale." } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the image and video models you can generate with, including each model's capabilities (aspect ratios, durations, reference-image support) and pricing source. Filter by modality, provider, or route. Start here to pick a modelId for createGeneration.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.aiMedia.listModels({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.ai_media.list_models(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark ai-media list-models \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/ai-media/models\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/ai-media/models';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List models", "x-displayName": "List models" } }, "/v1/teams/{teamId}/ai-media/model": { "get": { "tags": [ "Media generation" ], "operationId": "ai-media.getModel", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "modelId", "in": "query", "schema": { "type": "string", "description": "Catalog model id to fetch, e.g. \"google/veo-3.1-fast\". Carried as a query parameter because catalog ids contain a slash." }, "required": true, "description": "Catalog model id to fetch, e.g. \"google/veo-3.1-fast\". Carried as a query parameter because catalog ids contain a slash." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "label", "modality", "route", "routingProviderCode", "modelOwnerProviderCode", "providerModelId", "capabilitySchemaVersion", "capabilities", "defaultParams", "pricingSource", "enabled", "lifecycle" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "isNew": { "type": "boolean" }, "modality": { "type": "string", "enum": [ "image", "video" ] }, "route": { "type": "string", "enum": [ "openrouter", "fal" ] }, "routingProviderCode": { "type": "string", "enum": [ "google", "openai", "bytedance", "kuaishou", "alibaba", "minimax", "blackforestlabs", "openrouter", "fal", "xai", "runway", "recraft", "krea" ] }, "modelOwnerProviderCode": { "type": "string", "enum": [ "google", "openai", "bytedance", "kuaishou", "alibaba", "minimax", "blackforestlabs", "openrouter", "fal", "xai", "runway", "recraft", "krea" ] }, "providerModelId": { "type": "string" }, "providerEndpointId": { "type": "string" }, "capabilitySchemaVersion": { "type": "string" }, "capabilities": { "anyOf": [ { "type": "object", "required": [ "modality", "aspectRatios", "counts", "referenceImages", "allowedPassthroughParameters", "paramsSchemaId", "uiSchemaId" ], "properties": { "modality": { "type": "string", "enum": [ "image" ] }, "aspectRatios": { "type": "array", "items": { "type": "string", "enum": [ "1:1", "4:5", "9:16", "16:9", "3:2", "2:3", "4:3", "3:4" ] } }, "resolutions": { "type": "array", "items": { "type": "string", "enum": [ "512", "1K", "2K", "4K" ] } }, "qualities": { "type": "array", "items": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "sizes": { "type": "array", "items": { "type": "string" } }, "counts": { "type": "object", "required": [ "min", "max" ], "properties": { "min": { "type": "number" }, "max": { "type": "number" } }, "additionalProperties": false }, "referenceImages": { "type": "object", "required": [ "arity" ], "properties": { "arity": { "type": "string", "enum": [ "none", "single", "multi" ] }, "min": { "type": "number" }, "max": { "type": "number" } }, "additionalProperties": false }, "seed": { "type": "object", "required": [ "supported" ], "properties": { "supported": { "type": "boolean" }, "default": { "type": "boolean" } }, "additionalProperties": false }, "negativePrompt": { "type": "object", "required": [ "supported" ], "properties": { "supported": { "type": "boolean" }, "default": { "type": "boolean" } }, "additionalProperties": false }, "allowedPassthroughParameters": { "type": "array", "items": { "type": "string" } }, "paramsSchemaId": { "type": "string", "enum": [ "image.core.v1", "video.core.v1" ] }, "uiSchemaId": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "modality", "aspectRatios", "resolutions", "durationsSeconds", "referenceImages", "audio", "allowedPassthroughParameters", "paramsSchemaId", "uiSchemaId", "requiresEnrichmentBeforeAgentUse" ], "properties": { "modality": { "type": "string", "enum": [ "video" ] }, "aspectRatios": { "type": "array", "items": { "type": "string", "enum": [ "1:1", "4:5", "9:16", "16:9", "3:2", "2:3", "4:3", "3:4" ] } }, "resolutions": { "type": "array", "items": { "type": "string", "enum": [ "480p", "720p", "768p", "1080p", "2K" ] } }, "durationsSeconds": { "type": "array", "items": { "type": "number" } }, "referenceImages": { "type": "object", "required": [ "arity" ], "properties": { "arity": { "type": "string", "enum": [ "none", "single", "multi" ] }, "min": { "type": "number" }, "max": { "type": "number" } }, "additionalProperties": false }, "audio": { "type": "object", "required": [ "supported", "default" ], "properties": { "supported": { "type": "boolean" }, "default": { "type": "boolean" } }, "additionalProperties": false }, "seed": { "type": "object", "required": [ "supported" ], "properties": { "supported": { "type": "boolean" }, "default": { "type": "boolean" } }, "additionalProperties": false }, "negativePrompt": { "type": "object", "required": [ "supported" ], "properties": { "supported": { "type": "boolean" }, "default": { "type": "boolean" } }, "additionalProperties": false }, "allowedPassthroughParameters": { "type": "array", "items": { "type": "string" } }, "paramsSchemaId": { "type": "string", "enum": [ "image.core.v1", "video.core.v1" ] }, "uiSchemaId": { "type": "string" }, "requiresEnrichmentBeforeAgentUse": { "type": "boolean", "enum": [ true ] } }, "additionalProperties": false } ] }, "defaultParams": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "pricingSource": { "type": "string", "enum": [ "openrouter_usage", "provider_snapshot" ] }, "enabled": { "type": "boolean" }, "lifecycle": { "type": "string", "enum": [ "active", "deprecated", "retired" ] }, "replacedByModelId": { "type": "string" }, "retiredAt": { "type": "string" }, "listPrice": { "type": "object", "required": [ "unit", "unitPriceUsd", "pricingVerifiedAt", "stale" ], "properties": { "unit": { "type": "string", "description": "Billing unit the rate is quoted in: per_image or per_video_second." }, "unitPriceUsd": { "type": "number", "description": "Customer-facing price in USD per unit, margin already applied." }, "pricingVerifiedAt": { "type": "string", "description": "ISO-8601 instant the underlying pricing snapshot was last verified." }, "stale": { "type": "boolean", "description": "True when the snapshot is past the freshness limit; paid generation is blocked while stale." } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Fetch one generation model by id with its full capability matrix and default parameters. The modelId rides in the query string (not the path) because catalog ids contain a slash, e.g. \"google/veo-3.1-fast\".", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.aiMedia.getModel({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {\n \"modelId\": process.env.OCTOSPARK_MODEL_ID ?? \"modelId\",\n },\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.ai_media.get_model(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n query={\n \"modelId\": os.environ.get(\"OCTOSPARK_MODEL_ID\", \"modelId\"),\n }\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark ai-media get-model \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"query\":{\"modelId\":\"modelId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let model_id = env::var(\"OCTOSPARK_MODEL_ID\").unwrap_or_else(|_| \"modelId\".to_string());\n let url = format!(\"{}/v1/teams/{}/ai-media/model\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let query = [(\"modelId\", model_id.as_str())];\n request = request.query(&query);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final modelId = Platform.environment['OCTOSPARK_MODEL_ID'] ?? 'modelId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/ai-media/model';\n final uri = Uri.parse(url).replace(queryParameters: {\n 'modelId': modelId,\n });\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Model", "x-displayName": "Model" } }, "/v1/teams/{teamId}/ai-media/estimates": { "post": { "tags": [ "Media generation" ], "operationId": "ai-media.estimateGeneration", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "holdDecimillicents", "unit", "unitPriceUsd", "pricingVerifiedAt", "stale" ], "properties": { "holdDecimillicents": { "$ref": "#/components/schemas/Int" }, "unit": { "type": "string" }, "unitPriceUsd": { "type": "number" }, "pricingVerifiedAt": { "type": "string" }, "stale": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Preview what a generation would cost before committing. Send the same selections you would submit to createGeneration and get back the exact credit hold it would reserve, plus the unit price and pricing freshness. This spends nothing and creates no generation. It is a POST because the parameters are a body-shaped payload, not because it changes anything.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "sourceSurface", "modality", "modelId", "params" ], "properties": { "sourceSurface": { "type": "string", "enum": [ "studio", "agent", "editor", "persona" ], "description": "Where the generation would be started from (studio, agent, or editor). Used for attribution only." }, "modality": { "type": "string", "enum": [ "image", "video" ], "description": "What would be generated: image or video. Must match the chosen model and the shape of params." }, "modelId": { "type": "string", "description": "Catalog model id to price the generation against, e.g. \"google/veo-3.1-fast\"." }, "params": { "anyOf": [ { "type": "object", "required": [ "modality", "prompt" ], "properties": { "modality": { "type": "string", "enum": [ "image" ] }, "prompt": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "aspectRatio": { "type": "string", "enum": [ "1:1", "4:5", "9:16", "16:9", "3:2", "2:3", "4:3", "3:4" ] }, "resolution": { "type": "string", "enum": [ "512", "1K", "2K", "4K" ] }, "quality": { "type": "string", "enum": [ "low", "medium", "high" ] }, "count": { "type": "integer", "description": "a number between 1 and 10", "title": "between(1, 10)", "minimum": 1, "maximum": 10 }, "negativePrompt": { "type": "string" }, "seed": { "$ref": "#/components/schemas/Int" }, "referenceAssetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false }, { "type": "object", "required": [ "modality", "prompt" ], "properties": { "modality": { "type": "string", "enum": [ "video" ] }, "prompt": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "aspectRatio": { "type": "string", "enum": [ "1:1", "4:5", "9:16", "16:9", "3:2", "2:3", "4:3", "3:4" ] }, "resolution": { "type": "string", "enum": [ "480p", "720p", "768p", "1080p", "2K" ] }, "durationSeconds": { "$ref": "#/components/schemas/Int" }, "audio": { "type": "boolean" }, "negativePrompt": { "type": "string" }, "seed": { "$ref": "#/components/schemas/Int" }, "referenceAssetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false } ], "description": "The exact generation parameters you would submit, so the estimate matches what a real create would reserve." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.aiMedia.estimateGeneration({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.ai_media.estimate_generation(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark ai-media estimate-generation \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/ai-media/estimates\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/ai-media/estimates';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Estimate generation", "x-displayName": "Estimate generation" } }, "/v1/teams/{teamId}/ai-media/generations": { "get": { "tags": [ "Media generation" ], "operationId": "ai-media.listGenerations", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, "required": false, "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "Page size as a positive integer string; defaults to 25, capped at 100.", "default": "25", "examples": [ "25", "100" ] }, "required": false, "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt.", "examples": [ "createdAt" ] }, "required": false, "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt." }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc or desc; defaults to desc.", "default": "desc" }, "required": false, "description": "Sort direction: asc or desc; defaults to desc." }, { "name": "filter[status]", "in": "query", "schema": { "type": "string", "enum": [ "queued", "reserved", "running", "rate_limited", "ready", "failed", "cancelled", "skipped_insufficient_credits" ], "description": "Return only generations in this status (e.g. reserved, running, succeeded, failed, or cancelled)." }, "required": false, "description": "Return only generations in this status (e.g. reserved, running, succeeded, failed, or cancelled)." }, { "name": "filter[modality]", "in": "query", "schema": { "type": "string", "enum": [ "image", "video" ], "description": "Return only generations of this modality (image or video)." }, "required": false, "description": "Return only generations of this modality (image or video)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "organizationId", "sourceSurface", "modelId", "modality", "route", "status", "statusError", "primaryAssetId", "assetIds", "estimatedCostDecimillicents", "actualCostDecimillicents", "callerIdempotencyKey", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "organizationId": { "$ref": "#/components/schemas/UUID" }, "sourceSurface": { "type": "string", "enum": [ "studio", "agent", "editor", "persona" ] }, "modelId": { "type": "string" }, "modality": { "type": "string", "enum": [ "image", "video" ] }, "route": { "type": "string", "enum": [ "openrouter", "fal" ] }, "status": { "type": "string", "enum": [ "queued", "reserved", "running", "rate_limited", "ready", "failed", "cancelled", "skipped_insufficient_credits" ] }, "statusError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "estimatedCostDecimillicents": { "type": "number" }, "actualCostDecimillicents": { "type": "number" }, "callerIdempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the team's image and video generations with cursor pagination, newest first. Filter by status or modality to find in-flight, completed, or failed generations and the assets they produced.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.aiMedia.listGenerations({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.ai_media.list_generations(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark ai-media list-generations \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/ai-media/generations\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/ai-media/generations';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List generations", "x-displayName": "List generations" }, "post": { "tags": [ "Media generation" ], "operationId": "ai-media.createGeneration", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "organizationId", "sourceSurface", "modelId", "modality", "route", "status", "statusError", "primaryAssetId", "assetIds", "estimatedCostDecimillicents", "actualCostDecimillicents", "callerIdempotencyKey", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "organizationId": { "$ref": "#/components/schemas/UUID" }, "sourceSurface": { "type": "string", "enum": [ "studio", "agent", "editor", "persona" ] }, "modelId": { "type": "string" }, "modality": { "type": "string", "enum": [ "image", "video" ] }, "route": { "type": "string", "enum": [ "openrouter", "fal" ] }, "status": { "type": "string", "enum": [ "queued", "reserved", "running", "rate_limited", "ready", "failed", "cancelled", "skipped_insufficient_credits" ] }, "statusError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "estimatedCostDecimillicents": { "type": "number" }, "actualCostDecimillicents": { "type": "number" }, "callerIdempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Start an image or video generation. This spends credits: the server reserves a conservative hold up front (call estimateGeneration first to see it) and returns 201 with the generation in a reserved state; the provider work runs asynchronously, so poll getGeneration for completion. Send an idempotencyKey so a retry returns the original generation instead of charging twice.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "sourceSurface", "modality", "modelId", "params" ], "properties": { "sourceSurface": { "type": "string", "enum": [ "studio", "agent", "editor", "persona" ], "description": "Where the generation was started from (studio, agent, or editor). Used for attribution; it does not change how the media is produced." }, "modality": { "type": "string", "enum": [ "image", "video" ], "description": "What to generate: image or video. Must match the chosen model and the shape of params." }, "modelId": { "type": "string", "description": "Catalog model id to generate with, e.g. \"google/veo-3.1-fast\". List models to see the available ids and their capabilities." }, "params": { "anyOf": [ { "type": "object", "required": [ "modality", "prompt" ], "properties": { "modality": { "type": "string", "enum": [ "image" ] }, "prompt": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "aspectRatio": { "type": "string", "enum": [ "1:1", "4:5", "9:16", "16:9", "3:2", "2:3", "4:3", "3:4" ] }, "resolution": { "type": "string", "enum": [ "512", "1K", "2K", "4K" ] }, "quality": { "type": "string", "enum": [ "low", "medium", "high" ] }, "count": { "type": "integer", "description": "a number between 1 and 10", "title": "between(1, 10)", "minimum": 1, "maximum": 10 }, "negativePrompt": { "type": "string" }, "seed": { "$ref": "#/components/schemas/Int" }, "referenceAssetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false }, { "type": "object", "required": [ "modality", "prompt" ], "properties": { "modality": { "type": "string", "enum": [ "video" ] }, "prompt": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "aspectRatio": { "type": "string", "enum": [ "1:1", "4:5", "9:16", "16:9", "3:2", "2:3", "4:3", "3:4" ] }, "resolution": { "type": "string", "enum": [ "480p", "720p", "768p", "1080p", "2K" ] }, "durationSeconds": { "$ref": "#/components/schemas/Int" }, "audio": { "type": "boolean" }, "negativePrompt": { "type": "string" }, "seed": { "$ref": "#/components/schemas/Int" }, "referenceAssetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false } ], "description": "Generation parameters for the chosen modality (prompt, aspect ratio, duration, reference images, and so on). The shape must match the model's capabilities; mismatches are rejected." }, "promptPreview": { "type": "string", "description": "Short human-readable summary of the prompt, stored on the generation row for display in lists and history." }, "folderId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ], "description": "Media-library folder id to place the generated asset in. null or omitted uses the team default location." }, "chatSessionId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ], "description": "Agent chat session id to associate this generation with when it was started from /agent chat." }, "targetPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of a post to attach the generated media to once it completes." }, "idempotencyKey": { "type": "string", "description": "Client-supplied key so a retried request returns the original generation instead of starting (and charging for) a second one." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.aiMedia.createGeneration({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.ai_media.create_generation(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark ai-media create-generation \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/ai-media/generations\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/ai-media/generations';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create generation", "x-displayName": "Create generation" } }, "/v1/teams/{teamId}/ai-media/generations/{generationId}": { "get": { "tags": [ "Media generation" ], "operationId": "ai-media.getGeneration", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "generationId", "in": "path", "schema": { "type": "string", "description": "Media generation id (UUID), as returned by the create generation and list generations endpoints." }, "required": true, "description": "Media generation id (UUID), as returned by the create generation and list generations endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "organizationId", "sourceSurface", "modelId", "modality", "route", "status", "statusError", "primaryAssetId", "assetIds", "estimatedCostDecimillicents", "actualCostDecimillicents", "callerIdempotencyKey", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "organizationId": { "$ref": "#/components/schemas/UUID" }, "sourceSurface": { "type": "string", "enum": [ "studio", "agent", "editor", "persona" ] }, "modelId": { "type": "string" }, "modality": { "type": "string", "enum": [ "image", "video" ] }, "route": { "type": "string", "enum": [ "openrouter", "fal" ] }, "status": { "type": "string", "enum": [ "queued", "reserved", "running", "rate_limited", "ready", "failed", "cancelled", "skipped_insufficient_credits" ] }, "statusError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "estimatedCostDecimillicents": { "type": "number" }, "actualCostDecimillicents": { "type": "number" }, "callerIdempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Fetch one generation with its current status, the ids of any assets it produced, and its estimated and actual credit cost. Poll this after createGeneration to know when the media is ready.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.aiMedia.getGeneration({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n generationId: process.env.OCTOSPARK_GENERATION_ID ?? \"generationId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.ai_media.get_generation(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n generationId=os.environ.get(\"OCTOSPARK_GENERATION_ID\", \"generationId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark ai-media get-generation \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"generationId\":\"generationId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let generation_id = env::var(\"OCTOSPARK_GENERATION_ID\").unwrap_or_else(|_| \"generationId\".to_string());\n let url = format!(\"{}/v1/teams/{}/ai-media/generations/{}\", base_url.trim_end_matches('/'), team_id, generation_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final generationId = Platform.environment['OCTOSPARK_GENERATION_ID'] ?? 'generationId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/ai-media/generations/$generationId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Generation", "x-displayName": "Generation" } }, "/v1/teams/{teamId}/ai-media/generations/{generationId}/cancel": { "post": { "tags": [ "Media generation" ], "operationId": "ai-media.cancelGeneration", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "generationId", "in": "path", "schema": { "type": "string", "description": "Media generation id (UUID), as returned by the create generation and list generations endpoints." }, "required": true, "description": "Media generation id (UUID), as returned by the create generation and list generations endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "organizationId", "sourceSurface", "modelId", "modality", "route", "status", "statusError", "primaryAssetId", "assetIds", "estimatedCostDecimillicents", "actualCostDecimillicents", "callerIdempotencyKey", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "organizationId": { "$ref": "#/components/schemas/UUID" }, "sourceSurface": { "type": "string", "enum": [ "studio", "agent", "editor", "persona" ] }, "modelId": { "type": "string" }, "modality": { "type": "string", "enum": [ "image", "video" ] }, "route": { "type": "string", "enum": [ "openrouter", "fal" ] }, "status": { "type": "string", "enum": [ "queued", "reserved", "running", "rate_limited", "ready", "failed", "cancelled", "skipped_insufficient_credits" ] }, "statusError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "estimatedCostDecimillicents": { "type": "number" }, "actualCostDecimillicents": { "type": "number" }, "callerIdempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Cancel a generation that is still queued, reserved, or running, releasing its credit hold. Generations that have already completed or failed cannot be cancelled.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.aiMedia.cancelGeneration({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n generationId: process.env.OCTOSPARK_GENERATION_ID ?? \"generationId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.ai_media.cancel_generation(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n generationId=os.environ.get(\"OCTOSPARK_GENERATION_ID\", \"generationId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark ai-media cancel-generation \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"generationId\":\"generationId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let generation_id = env::var(\"OCTOSPARK_GENERATION_ID\").unwrap_or_else(|_| \"generationId\".to_string());\n let url = format!(\"{}/v1/teams/{}/ai-media/generations/{}/cancel\", base_url.trim_end_matches('/'), team_id, generation_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final generationId = Platform.environment['OCTOSPARK_GENERATION_ID'] ?? 'generationId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/ai-media/generations/$generationId/cancel';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.post(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Cancel generation", "x-displayName": "Cancel generation" } }, "/v1/support/config": { "get": { "tags": [ "Support" ], "operationId": "support.getSupportConfig", "parameters": [], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "enabled" ], "properties": { "email": { "type": "string" }, "enabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Get the public support contact address and feedback form availability.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.support.getSupportConfig()" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.support.get_support_config()" }, { "lang": "CLI", "label": "CLI", "source": "octospark support get-support-config" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let url = format!(\"{}/v1/support/config\", base_url.trim_end_matches('/'));\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/support/config';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Support config", "x-displayName": "Support config" } }, "/v1/support/reports": { "post": { "tags": [ "Support" ], "operationId": "support.submitSupportReport", "parameters": [], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "reference" ], "properties": { "reference": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Save a support report and delivery intents with a stable request UUID. Available without a subscription; authenticated identity is validated.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "requestId", "category", "description", "email", "route" ], "properties": { "requestId": { "type": "string", "description": "Client-generated UUID for this report. Reuse it with the same draft when retrying an unconfirmed submission.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "category": { "type": "string", "enum": [ "problem", "help", "suggestion" ], "description": "Choose problem to report a fault, help to request support, or suggestion to propose an improvement." }, "description": { "type": "string", "description": "a string that will be trimmed" }, "email": { "type": "string", "description": "a string that will be trimmed" }, "route": { "type": "string", "description": "Page path where the report originated. Only the route family is stored; identifiers, queries and fragments are discarded.", "title": "maxLength(300)", "maxLength": 300 }, "browser": { "type": "string", "description": "Optional coarse browser family and desktop or mobile type, without a full user agent or device identifiers.", "title": "maxLength(80)", "maxLength": 80 }, "release": { "type": "string", "description": "Optional deployed release SHA or version. Omit when unavailable.", "title": "maxLength(80)", "maxLength": 80, "pattern": "^[a-zA-Z0-9._-]*$" }, "sentryEventId": { "type": "string", "description": "Optional exact 32-character hexadecimal Sentry event ID returned when an error was captured. Omit for ordinary feedback; this does not confirm remote ingestion.", "pattern": "^[a-f0-9]{32}$" }, "website": { "type": "string", "description": "Spam-trap field. Leave empty or omit it; non-empty values are rejected.", "title": "maxLength(200)", "maxLength": 200 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.support.submitSupportReport({\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.support.submit_support_report(\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark support submit-support-report \\\n --request '{\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let url = format!(\"{}/v1/support/reports\", base_url.trim_end_matches('/'));\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/support/reports';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Submit support report", "x-displayName": "Submit support report" } }, "/v1/teams/{teamId}/agent-schedules": { "get": { "tags": [ "Agent schedules" ], "operationId": "agentSchedules.listAgentSchedules", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "ListAgentSchedulesResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentSchedulesResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the team's agent schedules, newest first. Each schedule is a recurring background agent run: a name, the brief the run starts from, a five-field UTC cron cadence, and the guardrails (per-run/daily credit ceilings, pending-item cap) the minute sweeper enforces before firing.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.agentSchedules.listAgentSchedules({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.agent_schedules.list_agent_schedules(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark agent-schedules list-agent-schedules \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/agent-schedules\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/agent-schedules';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List agent schedules", "x-displayName": "List agent schedules" }, "post": { "tags": [ "Agent schedules" ], "operationId": "agentSchedules.createAgentSchedule", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "Reuse this key with the same creation request after a lost response. The original automation is returned; a different request is rejected.", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": false, "description": "Reuse this key with the same creation request after a lost response. The original automation is returned; a different request is rejected." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "organizationId", "teamId", "name", "brief", "cadence", "nextRunAt", "lastRunAt", "perRunCreditCeilingDecimillicents", "dailyCreditCeilingDecimillicents", "pendingItemCap", "pausedAt", "createdBy", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "organizationId": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string", "description": "Display name for the automation, 1-120 characters.", "title": "maxLength(120)", "minLength": 1, "maxLength": 120 }, "brief": { "type": "string", "description": "The instruction the scheduled run starts from - the prompt handed to the agent.", "title": "maxLength(20000)", "minLength": 1, "maxLength": 20000 }, "cadence": { "type": "string", "description": "Five-field cron expression (minute hour day-of-month month day-of-week), evaluated in UTC. Invalid expressions are rejected 400.", "title": "maxLength(100)", "minLength": 1, "examples": [ "0 9 * * *", "*/30 * * * 1-5" ], "maxLength": 100 }, "nextRunAt": { "type": "string", "description": "When the schedule next fires (ISO-8601 UTC)." }, "lastRunAt": { "anyOf": [ { "type": "string", "description": "When the sweeper last fired this schedule (ISO-8601 UTC); null before the first run." }, { "type": "null" } ] }, "perRunCreditCeilingDecimillicents": { "$ref": "#/components/schemas/Int", "description": "Per-run credit ceiling in decimillicents. A scheduled run stops (incomplete, surfaced in the inbox) when it reaches this spend.", "title": "positive", "exclusiveMinimum": 0 }, "dailyCreditCeilingDecimillicents": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "Optional daily credit ceiling in decimillicents across all of this schedule's runs (UTC day). The sweeper skips firing once reached; null means no daily ceiling.", "title": "positive", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Optional daily credit ceiling in decimillicents across all of this schedule's runs (UTC day). The sweeper skips firing once reached; send null for no daily ceiling." }, "pendingItemCap": { "$ref": "#/components/schemas/Int", "description": "Skip firing while this many (or more) of the schedule's runs sit unreviewed in the inbox, 1-100 (default 10). Keeps a broken automation from flooding the queue.", "title": "lessThanOrEqualTo(100)", "minimum": 1, "maximum": 100 }, "pausedAt": { "anyOf": [ { "type": "string", "description": "When the schedule was paused (ISO-8601 UTC); null while active. A paused schedule never fires." }, { "type": "null" } ] }, "createdBy": { "$ref": "#/components/schemas/UUID" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create an active recurring agent schedule. The cadence is a five-field UTC cron expression; invalid cadences return 400. nextRunAt is computed server-side. Runs spend team credits within the supplied ceilings, which default to $100 per run and per day (1000000000 decimillicents each); explicit null removes the daily ceiling. Send an Idempotency-Key and reuse it with the same request after a lost response to return the existing schedule. Replays preserve subsequent edits and pause state; different requests return 409, and a deleted schedule returns 404 rather than being recreated.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentScheduleBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.agentSchedules.createAgentSchedule({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.agent_schedules.create_agent_schedule(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark agent-schedules create-agent-schedule \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/agent-schedules\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/agent-schedules';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create agent schedule", "x-displayName": "Create agent schedule" } }, "/v1/teams/{teamId}/agent-schedules/{scheduleId}": { "get": { "tags": [ "Agent schedules" ], "operationId": "agentSchedules.getAgentSchedule", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "scheduleId", "in": "path", "schema": { "type": "string", "description": "Agent schedule id (UUID), as returned by the list/create agent-schedules endpoints." }, "required": true, "description": "Agent schedule id (UUID), as returned by the list/create agent-schedules endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "AgentSchedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSchedule" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Fetch one agent schedule, including its next/last fire times and pause state.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.agentSchedules.getAgentSchedule({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n scheduleId: process.env.OCTOSPARK_SCHEDULE_ID ?? \"scheduleId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.agent_schedules.get_agent_schedule(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n scheduleId=os.environ.get(\"OCTOSPARK_SCHEDULE_ID\", \"scheduleId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark agent-schedules get-agent-schedule \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"scheduleId\":\"scheduleId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let schedule_id = env::var(\"OCTOSPARK_SCHEDULE_ID\").unwrap_or_else(|_| \"scheduleId\".to_string());\n let url = format!(\"{}/v1/teams/{}/agent-schedules/{}\", base_url.trim_end_matches('/'), team_id, schedule_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final scheduleId = Platform.environment['OCTOSPARK_SCHEDULE_ID'] ?? 'scheduleId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/agent-schedules/$scheduleId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Agent schedule", "x-displayName": "Agent schedule" }, "patch": { "tags": [ "Agent schedules" ], "operationId": "agentSchedules.updateAgentSchedule", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "scheduleId", "in": "path", "schema": { "type": "string", "description": "Agent schedule id (UUID), as returned by the list/create agent-schedules endpoints." }, "required": true, "description": "Agent schedule id (UUID), as returned by the list/create agent-schedules endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "AgentSchedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSchedule" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Edit an agent schedule. Omitted fields are left unchanged. Changing the cadence recomputes nextRunAt; `paused: true` stops firing (stamps pausedAt), `paused: false` resumes and recomputes nextRunAt from now so a long-paused schedule never replays missed runs.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentScheduleBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.agentSchedules.updateAgentSchedule({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n scheduleId: process.env.OCTOSPARK_SCHEDULE_ID ?? \"scheduleId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.agent_schedules.update_agent_schedule(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n scheduleId=os.environ.get(\"OCTOSPARK_SCHEDULE_ID\", \"scheduleId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark agent-schedules update-agent-schedule \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"scheduleId\":\"scheduleId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let schedule_id = env::var(\"OCTOSPARK_SCHEDULE_ID\").unwrap_or_else(|_| \"scheduleId\".to_string());\n let url = format!(\"{}/v1/teams/{}/agent-schedules/{}\", base_url.trim_end_matches('/'), team_id, schedule_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final scheduleId = Platform.environment['OCTOSPARK_SCHEDULE_ID'] ?? 'scheduleId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/agent-schedules/$scheduleId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Update agent schedule", "x-displayName": "Update agent schedule" }, "delete": { "tags": [ "Agent schedules" ], "operationId": "agentSchedules.deleteAgentSchedule", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "scheduleId", "in": "path", "schema": { "type": "string", "description": "Agent schedule id (UUID), as returned by the list/create agent-schedules endpoints." }, "required": true, "description": "Agent schedule id (UUID), as returned by the list/create agent-schedules endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Delete an agent schedule. This cannot be undone. Sessions the schedule already created keep their history - they are detached, never deleted.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.agentSchedules.deleteAgentSchedule({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n scheduleId: process.env.OCTOSPARK_SCHEDULE_ID ?? \"scheduleId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.agent_schedules.delete_agent_schedule(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n scheduleId=os.environ.get(\"OCTOSPARK_SCHEDULE_ID\", \"scheduleId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark agent-schedules delete-agent-schedule \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"scheduleId\":\"scheduleId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let schedule_id = env::var(\"OCTOSPARK_SCHEDULE_ID\").unwrap_or_else(|_| \"scheduleId\".to_string());\n let url = format!(\"{}/v1/teams/{}/agent-schedules/{}\", base_url.trim_end_matches('/'), team_id, schedule_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final scheduleId = Platform.environment['OCTOSPARK_SCHEDULE_ID'] ?? 'scheduleId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/agent-schedules/$scheduleId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete agent schedule", "x-displayName": "Delete agent schedule" } }, "/v1/teams/{teamId}/brands": { "get": { "tags": [ "Brands" ], "operationId": "brands.listBrands", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, "required": false, "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "Page size as a positive integer string; defaults to 25, capped at 100.", "default": "25", "examples": [ "25", "100" ] }, "required": false, "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt.", "examples": [ "createdAt" ] }, "required": false, "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt." }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc or desc; defaults to desc.", "default": "desc" }, "required": false, "description": "Sort direction: asc or desc; defaults to desc." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "organizationId", "name", "isPrimary", "language", "website", "businessDescription", "idealCustomer", "customerLocation", "colors", "logoAssetId", "contentTopics", "selectedSourceIds", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "isPrimary": { "type": "boolean" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "businessDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "idealCustomer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerLocation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "colors": { "anyOf": [ { "type": "object", "required": [ "primary", "secondary", "accent", "background", "text" ], "properties": { "primary": { "type": "string" }, "secondary": { "type": "string" }, "accent": { "type": "string" }, "background": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "logoAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentTopics": { "type": "array", "items": { "type": "string" } }, "selectedSourceIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the team's brands with cursor pagination. A brand is a durable content profile (voice, audience, topics, selected sources) that grounds /agent generation; isPrimary marks the default brand used when none is explicitly selected.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.brands.listBrands({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.brands.list_brands(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark brands list-brands \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/brands\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/brands';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List brands", "x-displayName": "List brands" }, "post": { "tags": [ "Brands" ], "operationId": "brands.createBrand", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "organizationId", "name", "isPrimary", "language", "website", "businessDescription", "idealCustomer", "customerLocation", "colors", "logoAssetId", "contentTopics", "selectedSourceIds", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "isPrimary": { "type": "boolean" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "businessDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "idealCustomer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerLocation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "colors": { "anyOf": [ { "type": "object", "required": [ "primary", "secondary", "accent", "background", "text" ], "properties": { "primary": { "type": "string" }, "secondary": { "type": "string" }, "accent": { "type": "string" }, "background": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "logoAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentTopics": { "type": "array", "items": { "type": "string" } }, "selectedSourceIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create a brand for the team. Only a name is required; fill in the profile fields (language, website, business description, ideal customer, content topics) as you learn them, since they steer /agent content generation. The team's first brand automatically becomes the primary; pass isPrimary to promote a later one at creation, which demotes the previous primary in the same transaction.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Display name for the brand, e.g. the company or product name.", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "isPrimary": { "type": "boolean", "description": "Make this brand the team default that /agent grounds on. The first brand is always primary; setting this on a later brand demotes the previous primary atomically." }, "language": { "anyOf": [ { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, { "type": "null" } ], "description": "Language the brand publishes in, e.g. \"English\" or \"German\". Generated content follows it." }, "website": { "anyOf": [ { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, { "type": "null" } ], "description": "The brand's website URL, used as grounding context for generation." }, "businessDescription": { "anyOf": [ { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, { "type": "null" } ], "description": "Free-text description of what the business does, in the brand's own words." }, "idealCustomer": { "anyOf": [ { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, { "type": "null" } ], "description": "Who the brand is talking to: the audience generated content should be written for." }, "customerLocation": { "anyOf": [ { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, { "type": "null" } ], "description": "Where the audience is, e.g. \"UK\" or \"US west coast\", so content can match locale and idiom." }, "colors": { "anyOf": [ { "type": "object", "required": [ "primary", "secondary", "accent", "background", "text" ], "properties": { "primary": { "type": "string" }, "secondary": { "type": "string" }, "accent": { "type": "string" }, "background": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ], "description": "The brand colour palette (primary, secondary, accent, background, text), applied to generated visuals." }, "logoAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ], "description": "Id of a team media asset (see the assets endpoints) to use as the brand logo. Upload the image first, then reference its asset id here." }, "contentTopics": { "type": "array", "items": { "type": "string", "description": "a string at most 120 character(s) long", "title": "maxLength(120)", "minLength": 1, "maxLength": 120 }, "description": "Topics the brand posts about; generation stays within these themes.", "title": "maxItems(50)", "maxItems": 50 }, "selectedSourceIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Ids of existing content sources this brand grounds on (see the sources endpoints). Empty means no source grounding.", "title": "maxItems(200)", "maxItems": 200 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.brands.createBrand({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.brands.create_brand(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark brands create-brand \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/brands\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/brands';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create brand", "x-displayName": "Create brand" } }, "/v1/teams/{teamId}/brands/{brandId}": { "get": { "tags": [ "Brands" ], "operationId": "brands.getBrand", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "brandId", "in": "path", "schema": { "type": "string", "description": "Brand id (UUID), as returned by the list brands and create brand endpoints." }, "required": true, "description": "Brand id (UUID), as returned by the list brands and create brand endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "organizationId", "name", "isPrimary", "language", "website", "businessDescription", "idealCustomer", "customerLocation", "colors", "logoAssetId", "contentTopics", "selectedSourceIds", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "isPrimary": { "type": "boolean" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "businessDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "idealCustomer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerLocation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "colors": { "anyOf": [ { "type": "object", "required": [ "primary", "secondary", "accent", "background", "text" ], "properties": { "primary": { "type": "string" }, "secondary": { "type": "string" }, "accent": { "type": "string" }, "background": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "logoAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentTopics": { "type": "array", "items": { "type": "string" } }, "selectedSourceIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Fetch one brand with its full profile: voice and audience fields, colour palette, content topics, and the ids of the content sources it grounds on. Use listBrands to discover brand ids first.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.brands.getBrand({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n brandId: process.env.OCTOSPARK_BRAND_ID ?? \"brandId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.brands.get_brand(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n brandId=os.environ.get(\"OCTOSPARK_BRAND_ID\", \"brandId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark brands get-brand \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"brandId\":\"brandId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let brand_id = env::var(\"OCTOSPARK_BRAND_ID\").unwrap_or_else(|_| \"brandId\".to_string());\n let url = format!(\"{}/v1/teams/{}/brands/{}\", base_url.trim_end_matches('/'), team_id, brand_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final brandId = Platform.environment['OCTOSPARK_BRAND_ID'] ?? 'brandId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/brands/$brandId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Brand", "x-displayName": "Brand" }, "patch": { "tags": [ "Brands" ], "operationId": "brands.updateBrand", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "brandId", "in": "path", "schema": { "type": "string", "description": "Brand id (UUID), as returned by the list brands and create brand endpoints." }, "required": true, "description": "Brand id (UUID), as returned by the list brands and create brand endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "organizationId", "name", "isPrimary", "language", "website", "businessDescription", "idealCustomer", "customerLocation", "colors", "logoAssetId", "contentTopics", "selectedSourceIds", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "isPrimary": { "type": "boolean" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "businessDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "idealCustomer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerLocation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "colors": { "anyOf": [ { "type": "object", "required": [ "primary", "secondary", "accent", "background", "text" ], "properties": { "primary": { "type": "string" }, "secondary": { "type": "string" }, "accent": { "type": "string" }, "background": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "logoAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentTopics": { "type": "array", "items": { "type": "string" } }, "selectedSourceIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Edit a brand's profile. Send only the fields you want to change; clear a nullable field by sending null. Promoting a brand to primary is deliberately not part of this endpoint: use setPrimaryBrand, so a workspace can never end up with zero or two primary brands.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string", "description": "New display name for the brand.", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "language": { "anyOf": [ { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, { "type": "null" } ], "description": "Language the brand publishes in; send null to clear it." }, "website": { "anyOf": [ { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, { "type": "null" } ], "description": "The brand's website URL; send null to clear it." }, "businessDescription": { "anyOf": [ { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, { "type": "null" } ], "description": "Free-text description of what the business does; send null to clear it." }, "idealCustomer": { "anyOf": [ { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, { "type": "null" } ], "description": "The audience generated content should be written for; send null to clear it." }, "customerLocation": { "anyOf": [ { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, { "type": "null" } ], "description": "Where the audience is; send null to clear it." }, "colors": { "anyOf": [ { "type": "object", "required": [ "primary", "secondary", "accent", "background", "text" ], "properties": { "primary": { "type": "string" }, "secondary": { "type": "string" }, "accent": { "type": "string" }, "background": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ], "description": "The brand colour palette; send null to clear it." }, "logoAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ], "description": "Id of a team media asset to use as the brand logo; send null to clear it." }, "contentTopics": { "type": "array", "items": { "type": "string", "description": "a string at most 120 character(s) long", "title": "maxLength(120)", "minLength": 1, "maxLength": 120 }, "description": "Replacement list of topics the brand posts about (the whole list is replaced, not merged).", "title": "maxItems(50)", "maxItems": 50 }, "selectedSourceIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Replacement list of content source ids this brand grounds on (the whole list is replaced, not merged).", "title": "maxItems(200)", "maxItems": 200 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.brands.updateBrand({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n brandId: process.env.OCTOSPARK_BRAND_ID ?? \"brandId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.brands.update_brand(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n brandId=os.environ.get(\"OCTOSPARK_BRAND_ID\", \"brandId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark brands update-brand \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"brandId\":\"brandId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let brand_id = env::var(\"OCTOSPARK_BRAND_ID\").unwrap_or_else(|_| \"brandId\".to_string());\n let url = format!(\"{}/v1/teams/{}/brands/{}\", base_url.trim_end_matches('/'), team_id, brand_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final brandId = Platform.environment['OCTOSPARK_BRAND_ID'] ?? 'brandId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/brands/$brandId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Update brand", "x-displayName": "Update brand" }, "delete": { "tags": [ "Brands" ], "operationId": "brands.deleteBrand", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "brandId", "in": "path", "schema": { "type": "string", "description": "Brand id (UUID), as returned by the list brands and create brand endpoints." }, "required": true, "description": "Brand id (UUID), as returned by the list brands and create brand endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Delete a brand from the team. Content already generated with it and the sources it selected are unaffected. The primary brand cannot be deleted (409): promote another brand with setPrimaryBrand first, so the workspace always keeps a grounding default.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.brands.deleteBrand({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n brandId: process.env.OCTOSPARK_BRAND_ID ?? \"brandId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.brands.delete_brand(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n brandId=os.environ.get(\"OCTOSPARK_BRAND_ID\", \"brandId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark brands delete-brand \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"brandId\":\"brandId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let brand_id = env::var(\"OCTOSPARK_BRAND_ID\").unwrap_or_else(|_| \"brandId\".to_string());\n let url = format!(\"{}/v1/teams/{}/brands/{}\", base_url.trim_end_matches('/'), team_id, brand_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final brandId = Platform.environment['OCTOSPARK_BRAND_ID'] ?? 'brandId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/brands/$brandId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete brand", "x-displayName": "Delete brand" } }, "/v1/teams/{teamId}/brands/{brandId}/set-primary": { "post": { "tags": [ "Brands" ], "operationId": "brands.setPrimaryBrand", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "brandId", "in": "path", "schema": { "type": "string", "description": "Brand id (UUID), as returned by the list brands and create brand endpoints." }, "required": true, "description": "Brand id (UUID), as returned by the list brands and create brand endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "organizationId", "name", "isPrimary", "language", "website", "businessDescription", "idealCustomer", "customerLocation", "colors", "logoAssetId", "contentTopics", "selectedSourceIds", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "isPrimary": { "type": "boolean" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "businessDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "idealCustomer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerLocation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "colors": { "anyOf": [ { "type": "object", "required": [ "primary", "secondary", "accent", "background", "text" ], "properties": { "primary": { "type": "string" }, "secondary": { "type": "string" }, "accent": { "type": "string" }, "background": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "logoAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentTopics": { "type": "array", "items": { "type": "string" } }, "selectedSourceIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Make this brand the team's primary: the default profile /agent grounds on when no brand is explicitly selected. The switch is atomic (the previous primary is demoted in the same transaction), so there is always exactly one primary brand.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.brands.setPrimaryBrand({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n brandId: process.env.OCTOSPARK_BRAND_ID ?? \"brandId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.brands.set_primary_brand(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n brandId=os.environ.get(\"OCTOSPARK_BRAND_ID\", \"brandId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark brands set-primary-brand \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"brandId\":\"brandId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let brand_id = env::var(\"OCTOSPARK_BRAND_ID\").unwrap_or_else(|_| \"brandId\".to_string());\n let url = format!(\"{}/v1/teams/{}/brands/{}/set-primary\", base_url.trim_end_matches('/'), team_id, brand_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final brandId = Platform.environment['OCTOSPARK_BRAND_ID'] ?? 'brandId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/brands/$brandId/set-primary';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.post(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Set primary brand", "x-displayName": "Set primary brand" } }, "/v1/teams/{teamId}/content/artifact-runs/{runId}": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.getContentArtifactRun", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "runId", "in": "path", "schema": { "type": "string", "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SlideshowArtifactRunResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideshowArtifactRunResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Get the current state of a slideshow generation or slide-regeneration run. Poll this resource, or stream its events endpoint, until the status becomes completed, failed, cancelled, or superseded.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.getContentArtifactRun({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n runId: process.env.OCTOSPARK_RUN_ID ?? \"runId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.get_content_artifact_run(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n runId=os.environ.get(\"OCTOSPARK_RUN_ID\", \"runId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows get-content-artifact-run \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"runId\":\"runId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let run_id = env::var(\"OCTOSPARK_RUN_ID\").unwrap_or_else(|_| \"runId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/artifact-runs/{}\", base_url.trim_end_matches('/'), team_id, run_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final runId = Platform.environment['OCTOSPARK_RUN_ID'] ?? 'runId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/artifact-runs/$runId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Content artifact run", "x-displayName": "Content artifact run" } }, "/v1/teams/{teamId}/content/artifact-runs/{runId}/bundle": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.getRunBundle", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "runId", "in": "path", "schema": { "type": "string", "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "MediaRunBundleResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaRunBundleResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Retrieve the saved prompt, tool versions, source files, references and outputs for an agent run. Agents use this bundle to inspect or continue work with its recorded runtime configuration.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.getRunBundle({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n runId: process.env.OCTOSPARK_RUN_ID ?? \"runId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.get_run_bundle(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n runId=os.environ.get(\"OCTOSPARK_RUN_ID\", \"runId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows get-run-bundle \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"runId\":\"runId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let run_id = env::var(\"OCTOSPARK_RUN_ID\").unwrap_or_else(|_| \"runId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/artifact-runs/{}/bundle\", base_url.trim_end_matches('/'), team_id, run_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final runId = Platform.environment['OCTOSPARK_RUN_ID'] ?? 'runId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/artifact-runs/$runId/bundle';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Run bundle", "x-displayName": "Run bundle" } }, "/v1/teams/{teamId}/content/artifact-runs/{runId}/cancel": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.cancelContentArtifactRun", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "runId", "in": "path", "schema": { "type": "string", "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "contentItemId", "kind", "status", "targetSlideId", "regenerationScope", "baseRevision", "resultRevision", "workflowId", "renderJobId", "outputAssetId", "errorCode", "diagnostics", "pauseReason", "maxSpendDecimillicents", "spentDecimillicents", "activeDurationMs", "links" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "generation", "slide_regeneration", "edit" ] }, "status": { "type": "string" }, "targetSlideId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "regenerationScope": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowRegenerationScope" }, { "type": "null" } ] }, "baseRevision": { "$ref": "#/components/schemas/Int" }, "resultRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "workflowId": { "type": "string" }, "renderJobId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "outputAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pauseReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSpendDecimillicents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spentDecimillicents": { "type": "number" }, "activeDurationMs": { "type": "number" }, "links": { "type": "object", "required": [ "self", "events", "slideshow" ], "properties": { "self": { "type": "string" }, "events": { "type": "string" }, "slideshow": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Request cancellation of active slideshow or meme creation work. Cancellation is asynchronous; poll the run until it stops. Completed assets and payment receipts remain available.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.cancelContentArtifactRun({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n runId: process.env.OCTOSPARK_RUN_ID ?? \"runId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.cancel_content_artifact_run(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n runId=os.environ.get(\"OCTOSPARK_RUN_ID\", \"runId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows cancel-content-artifact-run \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"runId\":\"runId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let run_id = env::var(\"OCTOSPARK_RUN_ID\").unwrap_or_else(|_| \"runId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/artifact-runs/{}/cancel\", base_url.trim_end_matches('/'), team_id, run_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final runId = Platform.environment['OCTOSPARK_RUN_ID'] ?? 'runId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/artifact-runs/$runId/cancel';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.post(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Cancel content artifact run", "x-displayName": "Cancel content artifact run" } }, "/v1/teams/{teamId}/content/artifact-runs/{runId}/chat/stream": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.streamContentArtifactRunChat", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "runId", "in": "path", "schema": { "type": "string", "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration." }, { "name": "afterSeq", "in": "query", "schema": { "type": "string", "description": "a string to be decoded into a number" }, "required": false, "description": "a string to be decoded into a number" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "a string", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Stream the saved Pi conversation and tool activity using the AI SDK UI Message Stream protocol. Resume with afterSeq or Last-Event-ID, using the sequence from transient data-run-event parts. Postgres supplies durable replay and Redis accelerates live updates. Disconnecting only stops the reader; the Temporal run continues. This read-only operation does not reserve or spend credits.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.streamContentArtifactRunChat({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n runId: process.env.OCTOSPARK_RUN_ID ?? \"runId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.stream_content_artifact_run_chat(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n runId=os.environ.get(\"OCTOSPARK_RUN_ID\", \"runId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows stream-content-artifact-run-chat \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"runId\":\"runId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let run_id = env::var(\"OCTOSPARK_RUN_ID\").unwrap_or_else(|_| \"runId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/artifact-runs/{}/chat/stream\", base_url.trim_end_matches('/'), team_id, run_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final runId = Platform.environment['OCTOSPARK_RUN_ID'] ?? 'runId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/artifact-runs/$runId/chat/stream';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Stream content artifact run chat", "x-displayName": "Stream content artifact run chat" } }, "/v1/teams/{teamId}/content/artifact-runs/{runId}/events": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.listContentArtifactRunEvents", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "runId", "in": "path", "schema": { "type": "string", "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration." }, { "name": "afterSeq", "in": "query", "schema": { "type": "string", "description": "a string to be decoded into a number" }, "required": false, "description": "a string to be decoded into a number" }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "a string to be decoded into a number" }, "required": false, "description": "a string to be decoded into a number" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "ContentJobEventsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentJobEventsResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Read ordered lifecycle events for one slideshow artifact run. Request JSON for polling, or send Accept: text/event-stream and resume with Last-Event-ID to follow the run without losing already-delivered events.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.listContentArtifactRunEvents({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n runId: process.env.OCTOSPARK_RUN_ID ?? \"runId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.list_content_artifact_run_events(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n runId=os.environ.get(\"OCTOSPARK_RUN_ID\", \"runId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows list-content-artifact-run-events \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"runId\":\"runId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let run_id = env::var(\"OCTOSPARK_RUN_ID\").unwrap_or_else(|_| \"runId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/artifact-runs/{}/events\", base_url.trim_end_matches('/'), team_id, run_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final runId = Platform.environment['OCTOSPARK_RUN_ID'] ?? 'runId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/artifact-runs/$runId/events';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List content artifact run events", "x-displayName": "List content artifact run events" } }, "/v1/teams/{teamId}/content/artifact-runs/{runId}/resume": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.resumeContentArtifactRun", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "runId", "in": "path", "schema": { "type": "string", "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "contentItemId", "kind", "status", "targetSlideId", "regenerationScope", "baseRevision", "resultRevision", "workflowId", "renderJobId", "outputAssetId", "errorCode", "diagnostics", "pauseReason", "maxSpendDecimillicents", "spentDecimillicents", "activeDurationMs", "links" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "generation", "slide_regeneration", "edit" ] }, "status": { "type": "string" }, "targetSlideId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "regenerationScope": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowRegenerationScope" }, { "type": "null" } ] }, "baseRevision": { "$ref": "#/components/schemas/Int" }, "resultRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "workflowId": { "type": "string" }, "renderJobId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "outputAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pauseReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSpendDecimillicents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spentDecimillicents": { "type": "number" }, "activeDurationMs": { "type": "number" }, "links": { "type": "object", "required": [ "self", "events", "slideshow" ], "properties": { "self": { "type": "string" }, "events": { "type": "string" }, "slideshow": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Resume a paused media run using its saved session and immutable run bundle. Runs with uncertain provider charges remain blocked until reconciled; resume does not create a replacement run.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.resumeContentArtifactRun({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n runId: process.env.OCTOSPARK_RUN_ID ?? \"runId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.resume_content_artifact_run(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n runId=os.environ.get(\"OCTOSPARK_RUN_ID\", \"runId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows resume-content-artifact-run \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"runId\":\"runId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let run_id = env::var(\"OCTOSPARK_RUN_ID\").unwrap_or_else(|_| \"runId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/artifact-runs/{}/resume\", base_url.trim_end_matches('/'), team_id, run_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final runId = Platform.environment['OCTOSPARK_RUN_ID'] ?? 'runId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/artifact-runs/$runId/resume';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.post(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Resume content artifact run", "x-displayName": "Resume content artifact run" } }, "/v1/teams/{teamId}/content/artifact-runs/{runId}/retry": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.retryContentArtifactRun", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "runId", "in": "path", "schema": { "type": "string", "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "contentItemId", "kind", "status", "targetSlideId", "regenerationScope", "baseRevision", "resultRevision", "workflowId", "renderJobId", "outputAssetId", "errorCode", "diagnostics", "pauseReason", "maxSpendDecimillicents", "spentDecimillicents", "activeDurationMs", "links" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "generation", "slide_regeneration", "edit" ] }, "status": { "type": "string" }, "targetSlideId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "regenerationScope": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowRegenerationScope" }, { "type": "null" } ] }, "baseRevision": { "$ref": "#/components/schemas/Int" }, "resultRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "workflowId": { "type": "string" }, "renderJobId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "outputAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pauseReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSpendDecimillicents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spentDecimillicents": { "type": "number" }, "activeDurationMs": { "type": "number" }, "links": { "type": "object", "required": [ "self", "events", "slideshow" ], "properties": { "self": { "type": "string" }, "events": { "type": "string" }, "slideshow": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Retry one failed slideshow generation or slide-regeneration run against the current slideshow revision. The new run reuses the exact persisted request, receives a new durable identity, respects team admission, and locks slideshow edits only while it is mutating the deck.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrySlideshowArtifactRunBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.retryContentArtifactRun({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n runId: process.env.OCTOSPARK_RUN_ID ?? \"runId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.retry_content_artifact_run(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n runId=os.environ.get(\"OCTOSPARK_RUN_ID\", \"runId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows retry-content-artifact-run \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"runId\":\"runId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let run_id = env::var(\"OCTOSPARK_RUN_ID\").unwrap_or_else(|_| \"runId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/artifact-runs/{}/retry\", base_url.trim_end_matches('/'), team_id, run_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final runId = Platform.environment['OCTOSPARK_RUN_ID'] ?? 'runId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/artifact-runs/$runId/retry';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Retry content artifact run", "x-displayName": "Retry content artifact run" } }, "/v1/teams/{teamId}/content/artifact-runs/{runId}/slideshow-source": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.seeSlideshowSourceForRun", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "runId", "in": "path", "schema": { "type": "string", "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SlideshowSourceForRunResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideshowSourceForRunResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Inspect the saved Remotion source associated with a slideshow run. Intended for agents that need to make source edits beyond the visual editor.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.seeSlideshowSourceForRun({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n runId: process.env.OCTOSPARK_RUN_ID ?? \"runId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.see_slideshow_source_for_run(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n runId=os.environ.get(\"OCTOSPARK_RUN_ID\", \"runId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows see-slideshow-source-for-run \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"runId\":\"runId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let run_id = env::var(\"OCTOSPARK_RUN_ID\").unwrap_or_else(|_| \"runId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/artifact-runs/{}/slideshow-source\", base_url.trim_end_matches('/'), team_id, run_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final runId = Platform.environment['OCTOSPARK_RUN_ID'] ?? 'runId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/artifact-runs/$runId/slideshow-source';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "See slideshow source for run", "x-displayName": "See slideshow source for run" } }, "/v1/teams/{teamId}/content/background-search": { "post": { "tags": [ "Media creation" ], "operationId": "mediaCreation.searchBackgrounds", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SearchBackgroundsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchBackgroundsResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Search approved stock providers for backgrounds, with existing library packs available as a fallback. Provider search usage may spend credits; send an Idempotency-Key for a safe retry.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchBackgroundsBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.mediaCreation.searchBackgrounds({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.media_creation.search_backgrounds(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark media-creation search-backgrounds \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/background-search\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/background-search';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Search backgrounds", "x-displayName": "Search backgrounds" } }, "/v1/teams/{teamId}/content/background-selection": { "post": { "tags": [ "Media creation" ], "operationId": "mediaCreation.selectBackground", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SelectBackgroundResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectBackgroundResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Record the required download attribution when selecting an Unsplash background. Call this after choosing a search result before using its image.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectBackgroundBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.mediaCreation.selectBackground({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.media_creation.select_background(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark media-creation select-background \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/background-selection\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/background-selection';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Select background", "x-displayName": "Select background" } }, "/v1/teams/{teamId}/content/green-screen-memes": { "post": { "tags": [ "Media creation" ], "operationId": "mediaCreation.createGreenScreenMeme", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "contentItemId", "kind", "status", "targetSlideId", "regenerationScope", "baseRevision", "resultRevision", "workflowId", "renderJobId", "outputAssetId", "errorCode", "diagnostics", "pauseReason", "maxSpendDecimillicents", "spentDecimillicents", "activeDurationMs", "links" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "generation", "slide_regeneration", "edit" ] }, "status": { "type": "string" }, "targetSlideId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "regenerationScope": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowRegenerationScope" }, { "type": "null" } ] }, "baseRevision": { "$ref": "#/components/schemas/Int" }, "resultRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "workflowId": { "type": "string" }, "renderJobId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "outputAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pauseReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSpendDecimillicents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spentDecimillicents": { "type": "number" }, "activeDurationMs": { "type": "number" }, "links": { "type": "object", "required": [ "self", "events", "slideshow" ], "properties": { "self": { "type": "string" }, "events": { "type": "string" }, "slideshow": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Composite a green-screen template over a chosen background and add captions. Rendering is asynchronous and uses the saved template calibration; poll the returned run and send an Idempotency-Key for a safe retry.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "templateAssetId", "backgroundAssetId", "title", "aspectRatio", "captions", "audio", "chromaKey" ], "properties": { "templateAssetId": { "$ref": "#/components/schemas/UUID" }, "backgroundAssetId": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ], "description": "Output proportions used to size the background and composition." }, "captions": { "type": "array", "items": { "type": "object", "required": [ "id", "text", "x", "y", "width", "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "text": { "type": "string", "description": "a string at most 2000 character(s) long", "title": "maxLength(2000)", "maxLength": 2000 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "maxItems": 20 }, "audio": { "type": "object", "required": [ "mode", "volume" ], "properties": { "mode": { "type": "string", "enum": [ "original", "mute" ] }, "volume": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false, "description": "Choose whether to keep or mute the template audio and its playback volume from zero to one." }, "chromaKey": { "type": "object", "required": [ "keyColor", "similarity", "blend", "despill", "version" ], "properties": { "keyColor": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}$", "pattern": "^#[0-9a-fA-F]{6}$" }, "similarity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "blend": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "despill": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "version": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, "confidence": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false, "description": "Saved template calibration for removing the screen colour and reducing colour spill. Editors obtain this from template metadata automatically." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.mediaCreation.createGreenScreenMeme({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.media_creation.create_green_screen_meme(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark media-creation create-green-screen-meme \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/green-screen-memes\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/green-screen-memes';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create green screen meme", "x-displayName": "Create green screen meme" } }, "/v1/teams/{teamId}/content/media-templates": { "post": { "tags": [ "Media creation" ], "operationId": "mediaCreation.promoteMemeTemplate", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "PromoteMemeTemplateResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteMemeTemplateResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Turn a completed AI image into a reusable meme template with one empty caption zone. Returns the template asset and a link to its editor.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteMemeTemplateBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.mediaCreation.promoteMemeTemplate({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.media_creation.promote_meme_template(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark media-creation promote-meme-template \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/media-templates\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/media-templates';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Promote meme template", "x-displayName": "Promote meme template" } }, "/v1/teams/{teamId}/content/media-templates/{assetId}/preview": { "get": { "tags": [ "Media creation" ], "operationId": "mediaCreation.getMediaTemplatePreview", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "assetId", "in": "path", "schema": { "type": "string", "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." }, "required": true, "description": "Media-library asset id (UUID), as returned by asset list, search, and upload endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "MediaTemplatePreviewResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaTemplatePreviewResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Get a same-team template preview and its saved caption or green-screen metadata. Use the returned URL and dimensions to initialise the editor.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.mediaCreation.getMediaTemplatePreview({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n assetId: process.env.OCTOSPARK_ASSET_ID ?? \"assetId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.media_creation.get_media_template_preview(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n assetId=os.environ.get(\"OCTOSPARK_ASSET_ID\", \"assetId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark media-creation get-media-template-preview \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"assetId\":\"assetId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let asset_id = env::var(\"OCTOSPARK_ASSET_ID\").unwrap_or_else(|_| \"assetId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/media-templates/{}/preview\", base_url.trim_end_matches('/'), team_id, asset_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final assetId = Platform.environment['OCTOSPARK_ASSET_ID'] ?? 'assetId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/media-templates/$assetId/preview';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Media template preview", "x-displayName": "Media template preview" } }, "/v1/teams/{teamId}/content/meme-image-generations": { "post": { "tags": [ "Media creation" ], "operationId": "mediaCreation.generateMemeImage", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "contentItemId", "kind", "status", "targetSlideId", "regenerationScope", "baseRevision", "resultRevision", "workflowId", "renderJobId", "outputAssetId", "errorCode", "diagnostics", "pauseReason", "maxSpendDecimillicents", "spentDecimillicents", "activeDurationMs", "links" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "generation", "slide_regeneration", "edit" ] }, "status": { "type": "string" }, "targetSlideId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "regenerationScope": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowRegenerationScope" }, { "type": "null" } ] }, "baseRevision": { "$ref": "#/components/schemas/Int" }, "resultRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "workflowId": { "type": "string" }, "renderJobId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "outputAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pauseReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSpendDecimillicents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spentDecimillicents": { "type": "number" }, "activeDurationMs": { "type": "number" }, "links": { "type": "object", "required": [ "self", "events", "slideshow" ], "properties": { "self": { "type": "string" }, "events": { "type": "string" }, "slideshow": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Generate a clean reusable meme image through the billed image pipeline. Optional caption or structured captions overlays the original afterwards. Poll the returned run bundle for templateAssetId, outputAssetIds, captions, and editorHref.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateMemeImageBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.mediaCreation.generateMemeImage({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.media_creation.generate_meme_image(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark media-creation generate-meme-image \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/meme-image-generations\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/meme-image-generations';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Generate meme image", "x-displayName": "Generate meme image" } }, "/v1/teams/{teamId}/content/memes": { "post": { "tags": [ "Media creation" ], "operationId": "mediaCreation.createImageMeme", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "contentItemId", "kind", "status", "targetSlideId", "regenerationScope", "baseRevision", "resultRevision", "workflowId", "renderJobId", "outputAssetId", "errorCode", "diagnostics", "pauseReason", "maxSpendDecimillicents", "spentDecimillicents", "activeDurationMs", "links" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "generation", "slide_regeneration", "edit" ] }, "status": { "type": "string" }, "targetSlideId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "regenerationScope": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowRegenerationScope" }, { "type": "null" } ] }, "baseRevision": { "$ref": "#/components/schemas/Int" }, "resultRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "workflowId": { "type": "string" }, "renderJobId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "outputAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pauseReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSpendDecimillicents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spentDecimillicents": { "type": "number" }, "activeDurationMs": { "type": "number" }, "links": { "type": "object", "required": [ "self", "events", "slideshow" ], "properties": { "self": { "type": "string" }, "events": { "type": "string" }, "slideshow": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Render a meme template with editable captions at its original size or a selected aspect ratio. Rendering is asynchronous; poll the returned run and send an Idempotency-Key to prevent duplicate work.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "templateAssetId", "title", "aspectRatio" ], "properties": { "templateAssetId": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "aspectRatio": { "type": "string", "enum": [ "original", "9:16", "16:9", "1:1", "4:5" ], "description": "Output proportions. Use original to preserve the template canvas and caption zones." }, "captions": { "type": "array", "items": { "type": "object", "required": [ "id", "text", "x", "y", "width", "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "text": { "type": "string", "description": "a string at most 2000 character(s) long", "title": "maxLength(2000)", "maxLength": 2000 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "maxItems": 20 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.mediaCreation.createImageMeme({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.media_creation.create_image_meme(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark media-creation create-image-meme \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/memes\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/memes';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create image meme", "x-displayName": "Create image meme" } }, "/v1/teams/{teamId}/content/render-jobs": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.listContentRenderJobs", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "a string to be decoded into a number" }, "required": false, "description": "a string to be decoded into a number" }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "a string at most 2048 character(s) long", "title": "maxLength(2048)", "minLength": 1, "maxLength": 2048 }, "required": false, "description": "a string at most 2048 character(s) long" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "running", "repairing", "pre_render_complete", "paused", "cancel_requested", "succeeded", "failed", "cancelled", "superseded", "queued", "validating", "rendering", "uploading", "succeeded", "failed", "cancel_requested", "cancelled", "superseded", "active", "finished" ], "description": "Filter by an exact queue status, active work, or finished work. Omit to list every status." }, "required": false, "description": "Filter by an exact queue status, active work, or finished work. Omit to list every status." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "ListContentRenderJobsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContentRenderJobsResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the shared durable media queue for slideshows, image memes and green-screen memes. Each row keeps its actual run or render job status; slideshow generation rows are replaced by their linked render job once queued. Results use newest-first timestamp and UUID pagination. Completed output references include only eligible same-team canonical asset IDs within retention.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.listContentRenderJobs({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.list_content_render_jobs(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows list-content-render-jobs \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/render-jobs\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/render-jobs';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List content render jobs", "x-displayName": "List content render jobs" } }, "/v1/teams/{teamId}/content/render-jobs/{renderJobId}": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.getContentRenderJob", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "renderJobId", "in": "path", "schema": { "type": "string", "description": "Render job id (UUID), as returned by createContentRenderJob or an artifact run.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Render job id (UUID), as returned by createContentRenderJob or an artifact run." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "ContentRenderJobDetailResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentRenderJobDetailResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Get one content render job, including its frozen project snapshot, creative hash, renderer version, progress state, output manifest, timing, and any failure diagnostics. Use the events endpoint when a caller needs incremental progress instead of polling this snapshot.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.getContentRenderJob({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n renderJobId: process.env.OCTOSPARK_RENDER_JOB_ID ?? \"renderJobId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.get_content_render_job(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n renderJobId=os.environ.get(\"OCTOSPARK_RENDER_JOB_ID\", \"renderJobId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows get-content-render-job \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"renderJobId\":\"renderJobId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let render_job_id = env::var(\"OCTOSPARK_RENDER_JOB_ID\").unwrap_or_else(|_| \"renderJobId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/render-jobs/{}\", base_url.trim_end_matches('/'), team_id, render_job_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final renderJobId = Platform.environment['OCTOSPARK_RENDER_JOB_ID'] ?? 'renderJobId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/render-jobs/$renderJobId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Content render job", "x-displayName": "Content render job" } }, "/v1/teams/{teamId}/content/render-jobs/{renderJobId}/cancel": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.cancelContentRenderJob", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "renderJobId", "in": "path", "schema": { "type": "string", "description": "Render job id (UUID), as returned by createContentRenderJob or an artifact run.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Render job id (UUID), as returned by createContentRenderJob or an artifact run." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "contentItemId", "artifactRunId", "payloadId", "payloadRevision", "creativeHash", "rendererVersion", "status", "workflowId", "outputWidth", "outputHeight", "slideCount", "pixelCount", "outputManifest", "durationMs", "hostId", "errorClass", "errorCode", "diagnostics", "retryable", "createdAt", "startedAt", "completedAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "artifactRunId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "payloadId": { "$ref": "#/components/schemas/UUID" }, "payloadRevision": { "$ref": "#/components/schemas/Int" }, "creativeHash": { "type": "string" }, "rendererVersion": { "type": "string" }, "status": { "type": "string" }, "workflowId": { "type": "string" }, "outputWidth": { "$ref": "#/components/schemas/Int" }, "outputHeight": { "$ref": "#/components/schemas/Int" }, "slideCount": { "$ref": "#/components/schemas/Int" }, "pixelCount": { "$ref": "#/components/schemas/Int" }, "outputManifest": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "durationMs": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "hostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorClass": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Request cancellation of a queued or active content render job and return its updated state. Cancellation is asynchronous once host work has started, so follow the job or event stream until it reaches a terminal state; send an Idempotency-Key for safe retries.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.cancelContentRenderJob({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n renderJobId: process.env.OCTOSPARK_RENDER_JOB_ID ?? \"renderJobId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.cancel_content_render_job(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n renderJobId=os.environ.get(\"OCTOSPARK_RENDER_JOB_ID\", \"renderJobId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows cancel-content-render-job \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"renderJobId\":\"renderJobId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let render_job_id = env::var(\"OCTOSPARK_RENDER_JOB_ID\").unwrap_or_else(|_| \"renderJobId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/render-jobs/{}/cancel\", base_url.trim_end_matches('/'), team_id, render_job_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final renderJobId = Platform.environment['OCTOSPARK_RENDER_JOB_ID'] ?? 'renderJobId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/render-jobs/$renderJobId/cancel';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.post(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Cancel content render job", "x-displayName": "Cancel content render job" } }, "/v1/teams/{teamId}/content/render-jobs/{renderJobId}/events": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.listContentRenderJobEvents", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "renderJobId", "in": "path", "schema": { "type": "string", "description": "Render job id (UUID), as returned by createContentRenderJob or an artifact run.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Render job id (UUID), as returned by createContentRenderJob or an artifact run." }, { "name": "afterSeq", "in": "query", "schema": { "type": "string", "description": "a string to be decoded into a number" }, "required": false, "description": "a string to be decoded into a number" }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "a string to be decoded into a number" }, "required": false, "description": "a string to be decoded into a number" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "ContentJobEventsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentJobEventsResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Read ordered progress events for one content render job. Request JSON for polling, or send Accept: text/event-stream and resume with Last-Event-ID to follow validation, rendering, upload, cancellation, and completion.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.listContentRenderJobEvents({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n renderJobId: process.env.OCTOSPARK_RENDER_JOB_ID ?? \"renderJobId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.list_content_render_job_events(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n renderJobId=os.environ.get(\"OCTOSPARK_RENDER_JOB_ID\", \"renderJobId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows list-content-render-job-events \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"renderJobId\":\"renderJobId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let render_job_id = env::var(\"OCTOSPARK_RENDER_JOB_ID\").unwrap_or_else(|_| \"renderJobId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/render-jobs/{}/events\", base_url.trim_end_matches('/'), team_id, render_job_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final renderJobId = Platform.environment['OCTOSPARK_RENDER_JOB_ID'] ?? 'renderJobId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/render-jobs/$renderJobId/events';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List content render job events", "x-displayName": "List content render job events" } }, "/v1/teams/{teamId}/content/renders": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.listContentRenders", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "page", "in": "query", "schema": { "type": "string", "description": "a string to be decoded into a number" }, "required": false, "description": "a string to be decoded into a number" }, { "name": "perPage", "in": "query", "schema": { "type": "string", "description": "a string to be decoded into a number" }, "required": false, "description": "a string to be decoded into a number" }, { "name": "sortField", "in": "query", "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "completedAt", "title", "status", "artifactKind" ], "description": "Field to sort by. Defaults to createdAt; UUID is the stable tie breaker." }, "required": false, "description": "Field to sort by. Defaults to createdAt; UUID is the stable tie breaker." }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "description": "Ascending or descending order. Defaults to DESC." }, "required": false, "description": "Ascending or descending order. Defaults to DESC." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "running", "repairing", "pre_render_complete", "paused", "cancel_requested", "succeeded", "failed", "cancelled", "superseded", "queued", "validating", "rendering", "uploading", "succeeded", "failed", "cancel_requested", "cancelled", "superseded", "active", "finished" ], "description": "An exact durable status, active work, or finished work." }, "required": false, "description": "An exact durable status, active work, or finished work." }, { "name": "mediaKind", "in": "query", "schema": { "type": "string", "enum": [ "slideshow", "image_meme", "green_screen_meme" ], "description": "Slideshow, image meme, or green-screen meme authoring kind." }, "required": false, "description": "Slideshow, image meme, or green-screen meme authoring kind." }, { "name": "search", "in": "query", "schema": { "type": "string", "description": "Case-insensitive literal title substring. Empty search applies no title filter.", "title": "maxLength(500)", "maxLength": 500 }, "required": false, "description": "Case-insensitive literal title substring. Empty search applies no title filter." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "A page of matching durable renders and the total across the same tenant-scoped filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContentRendersResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Browse this team’s renders with numbered pages, server-side sorting and title, status or media-kind filters. The total matches the same filters and linked slideshow run/render entries are deduplicated. Output metadata and fresh previews include only completed, non-deleted eligible team assets; this read-only operation does not spend credits.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.listContentRenders({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.list_content_renders(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows list-content-renders \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/renders\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/renders';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List content renders", "x-displayName": "List content renders" } }, "/v1/teams/{teamId}/content/slideshows": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.listSlideshows", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, "required": false, "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "Page size as a positive integer string; defaults to 25, capped at 100.", "default": "25", "examples": [ "25", "100" ] }, "required": false, "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt.", "examples": [ "createdAt" ] }, "required": false, "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt." }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc or desc; defaults to desc.", "default": "desc" }, "required": false, "description": "Sort direction: asc or desc; defaults to desc." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SlideshowListResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideshowListResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List a team's slideshow artifacts with cursor pagination, newest first by default. Each item reports its current revision and whether the latest attached render still matches the current creative hash.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.listSlideshows({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.list_slideshows(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows list-slideshows \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List slideshows", "x-displayName": "List slideshows" }, "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.createSlideshow", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "contentItemId", "teamId", "sourceContentItemId", "title", "status", "payloadId", "revision", "creativeHash", "currentCreativeHash", "renderedCreativeHash", "renderFresh", "activeRun", "latestRun", "latestRenderJob", "project", "assetRefs", "links" ], "properties": { "contentItemId": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "sourceContentItemId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "payloadId": { "$ref": "#/components/schemas/UUID" }, "revision": { "$ref": "#/components/schemas/Int" }, "creativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currentCreativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "renderedCreativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "renderFresh": { "type": "boolean" }, "browserPreviewUrl": { "type": "string" }, "previewCreativeHash": { "type": "string" }, "activeRun": { "anyOf": [ { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "latestRun": { "anyOf": [ { "type": "object", "required": [ "id", "status", "errorCode", "diagnostics" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ], "description": "The most recent agent run whatever its outcome, so a failure is visible without having kept its run id." }, "latestRenderJob": { "anyOf": [ { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "project": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowProjectV1" }, { "type": "null" } ] }, "assetRefs": { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, "links": { "type": "object", "required": [ "self", "revisions", "latestRenderJob" ], "properties": { "self": { "type": "string" }, "revisions": { "type": "string" }, "latestRenderJob": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create a slideshow from a complete deterministic project when the caller already controls every slide, asset binding, style, and renderer setting. This path performs no AI generation; autoRender can queue the first render, and Idempotency-Key makes an exact retry safe.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSlideshowBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.createSlideshow({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.create_slideshow(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows create-slideshow \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create slideshow", "x-displayName": "Create slideshow" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.getSlideshow", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SlideshowArtifactResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideshowArtifactResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Fetch one slideshow and its complete current project, ordered asset references, revision, creative hashes, and navigation links. Read expectedRevision from this response before editing, undoing, duplicating, regenerating, or rendering.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.getSlideshow({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.get_slideshow(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows get-slideshow \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Slideshow", "x-displayName": "Slideshow" }, "delete": { "tags": [ "Slideshows" ], "operationId": "slideshows.deleteSlideshow", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" }, { "name": "expectedRevision", "in": "query", "schema": { "type": "string", "description": "a string to be decoded into a number" }, "required": true, "description": "a string to be decoded into a number" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "DeleteSlideshowResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSlideshowResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Soft-delete the authoring slideshow and atomically request cancellation of its active creation and render work. Works before generation completes. Supply the current expectedRevision (zero only if no payload exists) and Idempotency-Key. Payment receipts, native sessions and retention archives remain intact; published platform posts are not deleted.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.deleteSlideshow({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n query: {\n \"expectedRevision\": process.env.OCTOSPARK_EXPECTED_REVISION ?? \"expectedRevision\",\n },\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.delete_slideshow(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\"),\n query={\n \"expectedRevision\": os.environ.get(\"OCTOSPARK_EXPECTED_REVISION\", \"expectedRevision\"),\n }\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows delete-slideshow \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"},\"query\":{\"expectedRevision\":\"expectedRevision\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let expected_revision = env::var(\"OCTOSPARK_EXPECTED_REVISION\").unwrap_or_else(|_| \"expectedRevision\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let query = [(\"expectedRevision\", expected_revision.as_str())];\n request = request.query(&query);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final expectedRevision = Platform.environment['OCTOSPARK_EXPECTED_REVISION'] ?? 'expectedRevision';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId';\n final uri = Uri.parse(url).replace(queryParameters: {\n 'expectedRevision': expectedRevision,\n });\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete slideshow", "x-displayName": "Delete slideshow" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}/artifact-runs/active": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.getActiveContentArtifactRun", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SlideshowArtifactRunResponse", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowArtifactRunResponse" }, { "type": "null" } ] } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Get the newest active generation or regeneration run for one slideshow. Returns null when the slideshow exists but has no queued, running, repairing, or pre-render run. Use this to restore editor progress and lock state after loading a canonical URL without a run id.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.getActiveContentArtifactRun({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.get_active_content_artifact_run(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows get-active-content-artifact-run \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}/artifact-runs/active\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId/artifact-runs/active';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Active content artifact run", "x-displayName": "Active content artifact run" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}/chat": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.getSlideshowChat", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SlideshowChatResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideshowChatResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Load the saved conversation for a slideshow editor, including projected agent messages and tool activity. Use it to restore the chat when reopening a project.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.getSlideshowChat({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.get_slideshow_chat(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows get-slideshow-chat \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}/chat\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId/chat';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Slideshow chat", "x-displayName": "Slideshow chat" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}/commands": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.applySlideshowCommands", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "slideshow", "revision", "run" ], "properties": { "status": { "type": "string", "enum": [ "applied", "queued" ] }, "slideshow": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowArtifactResponse" }, { "type": "null" } ] }, "revision": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowRevisionResponse" }, { "type": "null" } ] }, "run": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowArtifactRunResponse" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Edit a slideshow by describing what you want changed rather than sending a whole project. Immediate commands commit as the next revision and return it; background commands (image generation or search, image packs, custom components) queue one durable run and return it - several background image requests in one call become a single run that works through the slides in order. Pass the current expectedRevision and an Idempotency-Key.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplySlideshowCommandsBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.applySlideshowCommands({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.apply_slideshow_commands(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows apply-slideshow-commands \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}/commands\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId/commands';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Apply slideshow commands", "x-displayName": "Apply slideshow commands" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}/duplicate": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.duplicateSlideshow", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "contentItemId", "teamId", "sourceContentItemId", "title", "status", "payloadId", "revision", "creativeHash", "currentCreativeHash", "renderedCreativeHash", "renderFresh", "activeRun", "latestRun", "latestRenderJob", "project", "assetRefs", "links" ], "properties": { "contentItemId": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "sourceContentItemId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "payloadId": { "$ref": "#/components/schemas/UUID" }, "revision": { "$ref": "#/components/schemas/Int" }, "creativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currentCreativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "renderedCreativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "renderFresh": { "type": "boolean" }, "browserPreviewUrl": { "type": "string" }, "previewCreativeHash": { "type": "string" }, "activeRun": { "anyOf": [ { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "latestRun": { "anyOf": [ { "type": "object", "required": [ "id", "status", "errorCode", "diagnostics" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ], "description": "The most recent agent run whatever its outcome, so a failure is visible without having kept its run id." }, "latestRenderJob": { "anyOf": [ { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "project": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowProjectV1" }, { "type": "null" } ] }, "assetRefs": { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, "links": { "type": "object", "required": [ "self", "revisions", "latestRenderJob" ], "properties": { "self": { "type": "string" }, "revisions": { "type": "string" }, "latestRenderJob": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create an independent draft copy of a slideshow's current creative project. The duplicate keeps reusable creative inputs but receives new artifact identities and no inherited run, render, or publish state; expectedRevision and Idempotency-Key protect against stale or repeated requests.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateSlideshowBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.duplicateSlideshow({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.duplicate_slideshow(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows duplicate-slideshow \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}/duplicate\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId/duplicate';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Duplicate slideshow", "x-displayName": "Duplicate slideshow" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}/edits": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.createSlideshowEditRun", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "contentItemId", "kind", "status", "targetSlideId", "regenerationScope", "baseRevision", "resultRevision", "workflowId", "renderJobId", "outputAssetId", "errorCode", "diagnostics", "pauseReason", "maxSpendDecimillicents", "spentDecimillicents", "activeDurationMs", "links" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "generation", "slide_regeneration", "edit" ] }, "status": { "type": "string" }, "targetSlideId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "regenerationScope": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowRegenerationScope" }, { "type": "null" } ] }, "baseRevision": { "$ref": "#/components/schemas/Int" }, "resultRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "workflowId": { "type": "string" }, "renderJobId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "outputAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pauseReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSpendDecimillicents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spentDecimillicents": { "type": "number" }, "activeDurationMs": { "type": "number" }, "links": { "type": "object", "required": [ "self", "events", "slideshow" ], "properties": { "self": { "type": "string" }, "events": { "type": "string" }, "slideshow": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Ask the agent to edit a slideshow at its current revision, optionally targeting a selected element. The asynchronous run preserves an editable project and may spend credits; use an Idempotency-Key for retries.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSlideshowEditRunBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.createSlideshowEditRun({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.create_slideshow_edit_run(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows create-slideshow-edit-run \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}/edits\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId/edits';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create slideshow edit run", "x-displayName": "Create slideshow edit run" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}/project": { "put": { "tags": [ "Slideshows" ], "operationId": "slideshows.saveSlideshowProject", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "slideshow", "revision" ], "properties": { "slideshow": { "$ref": "#/components/schemas/SlideshowArtifactResponse" }, "revision": { "$ref": "#/components/schemas/SlideshowRevisionResponse" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Commit a complete slideshow project as the next revision. The project document is the unit of truth: send the whole edited project with the expectedRevision it was based on, and the request is refused if another edit or agent run has already advanced the slideshow. Pass an Idempotency-Key so a retry replays the first result instead of committing twice.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveSlideshowProjectBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.saveSlideshowProject({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.save_slideshow_project(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows save-slideshow-project \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}/project\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.put(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId/project';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.put(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Save slideshow project", "x-displayName": "Save slideshow project" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}/redo": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.redoSlideshow", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "slideshow", "revision" ], "properties": { "slideshow": { "$ref": "#/components/schemas/SlideshowArtifactResponse" }, "revision": { "$ref": "#/components/schemas/SlideshowRevisionResponse" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Redo the immediately preceding slideshow undo by replaying the original forward operations as a new edit revision. Any intervening edit invalidates redo.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedoSlideshowBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.redoSlideshow({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.redo_slideshow(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows redo-slideshow \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}/redo\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId/redo';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Redo slideshow", "x-displayName": "Redo slideshow" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}/render-jobs": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.createContentRenderJob", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "contentItemId", "artifactRunId", "payloadId", "payloadRevision", "creativeHash", "rendererVersion", "status", "workflowId", "outputWidth", "outputHeight", "slideCount", "pixelCount", "outputManifest", "durationMs", "hostId", "errorClass", "errorCode", "diagnostics", "retryable", "createdAt", "startedAt", "completedAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "artifactRunId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "payloadId": { "$ref": "#/components/schemas/UUID" }, "payloadRevision": { "$ref": "#/components/schemas/Int" }, "creativeHash": { "type": "string" }, "rendererVersion": { "type": "string" }, "status": { "type": "string" }, "workflowId": { "type": "string" }, "outputWidth": { "$ref": "#/components/schemas/Int" }, "outputHeight": { "$ref": "#/components/schemas/Int" }, "slideCount": { "$ref": "#/components/schemas/Int" }, "pixelCount": { "$ref": "#/components/schemas/Int" }, "outputManifest": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "durationMs": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "hostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorClass": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Queue a Remotion render from the slideshow's exact current revision and frozen creative hash. Local render-host work records usage but is not billable; pass expectedRevision to reject stale requests and Idempotency-Key to avoid duplicate jobs.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderContentArtifactBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.createContentRenderJob({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.create_content_render_job(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows create-content-render-job \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}/render-jobs\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId/render-jobs';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create content render job", "x-displayName": "Create content render job" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}/render-jobs/latest": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.getLatestContentRenderJob", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "ContentRenderJobResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentRenderJobResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Get the newest render job created for a slideshow. Use this after fetching a slideshow when you need its latest render state without already knowing a render job id; a missing job returns 404.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.getLatestContentRenderJob({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.get_latest_content_render_job(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows get-latest-content-render-job \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}/render-jobs/latest\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId/render-jobs/latest';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Latest content render job", "x-displayName": "Latest content render job" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}/revisions": { "get": { "tags": [ "Slideshows" ], "operationId": "slideshows.listSlideshowRevisions", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SlideshowRevisionsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideshowRevisionsResponse" } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List a slideshow's immutable revision history with cursor pagination, oldest first by default. Each entry records how that revision came about: who committed it, whether it was an edit, undo, or agent run, the semantic commands it accepted, and the creative hash it pinned.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.listSlideshowRevisions({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.list_slideshow_revisions(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows list-slideshow-revisions \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}/revisions\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId/revisions';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List slideshow revisions", "x-displayName": "List slideshow revisions" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}/slides/{slideId}/regenerations": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.regenerateSlideshowSlide", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." }, { "name": "slideId", "in": "path", "schema": { "type": "string", "description": "Slide id (UUID) from the slideshow project returned by getSlideshow.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slide id (UUID) from the slideshow project returned by getSlideshow." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "contentItemId", "kind", "status", "targetSlideId", "regenerationScope", "baseRevision", "resultRevision", "workflowId", "renderJobId", "outputAssetId", "errorCode", "diagnostics", "pauseReason", "maxSpendDecimillicents", "spentDecimillicents", "activeDurationMs", "links" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "generation", "slide_regeneration", "edit" ] }, "status": { "type": "string" }, "targetSlideId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "regenerationScope": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowRegenerationScope" }, { "type": "null" } ] }, "baseRevision": { "$ref": "#/components/schemas/Int" }, "resultRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "workflowId": { "type": "string" }, "renderJobId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "outputAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pauseReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSpendDecimillicents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spentDecimillicents": { "type": "number" }, "activeDurationMs": { "type": "number" }, "links": { "type": "object", "required": [ "self", "events", "slideshow" ], "properties": { "self": { "type": "string" }, "events": { "type": "string" }, "slideshow": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Start an asynchronous agentic revision of one slide, scoped to all content, text, or imagery. The run may use paid AI or media tools, commits only if expectedRevision is still current, and can optionally render the result; follow the returned links and use Idempotency-Key for safe retries.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegenerateSlideshowSlideBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.regenerateSlideshowSlide({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n slideId: process.env.OCTOSPARK_SLIDE_ID ?? \"slideId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.regenerate_slideshow_slide(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\"),\n slideId=os.environ.get(\"OCTOSPARK_SLIDE_ID\", \"slideId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows regenerate-slideshow-slide \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\",\"slideId\":\"slideId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let slide_id = env::var(\"OCTOSPARK_SLIDE_ID\").unwrap_or_else(|_| \"slideId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}/slides/{}/regenerations\", base_url.trim_end_matches('/'), team_id, content_item_id, slide_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final slideId = Platform.environment['OCTOSPARK_SLIDE_ID'] ?? 'slideId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId/slides/$slideId/regenerations';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Regenerate slideshow slide", "x-displayName": "Regenerate slideshow slide" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}/source-revisions": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.createSlideshowSourceRevision", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "contentItemId", "kind", "status", "targetSlideId", "regenerationScope", "baseRevision", "resultRevision", "workflowId", "renderJobId", "outputAssetId", "errorCode", "diagnostics", "pauseReason", "maxSpendDecimillicents", "spentDecimillicents", "activeDurationMs", "links" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "generation", "slide_regeneration", "edit" ] }, "status": { "type": "string" }, "targetSlideId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "regenerationScope": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowRegenerationScope" }, { "type": "null" } ] }, "baseRevision": { "$ref": "#/components/schemas/Int" }, "resultRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "workflowId": { "type": "string" }, "renderJobId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "outputAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pauseReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSpendDecimillicents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spentDecimillicents": { "type": "number" }, "activeDurationMs": { "type": "number" }, "links": { "type": "object", "required": [ "self", "events", "slideshow" ], "properties": { "self": { "type": "string" }, "events": { "type": "string" }, "slideshow": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Save an agent-edited Remotion source revision and validate it through compilation and rendering before promotion. Supply the expected current revision and an Idempotency-Key for a safe retry.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSlideshowSourceRevisionBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.createSlideshowSourceRevision({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.create_slideshow_source_revision(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows create-slideshow-source-revision \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}/source-revisions\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId/source-revisions';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create slideshow source revision", "x-displayName": "Create slideshow source revision" } }, "/v1/teams/{teamId}/content/slideshows/{contentItemId}/undo": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.undoSlideshow", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "path", "schema": { "type": "string", "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Slideshow content item id (UUID), as returned by createSlideshow, createSlideshowGeneration, or listSlideshows." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "slideshow", "revision" ], "properties": { "slideshow": { "$ref": "#/components/schemas/SlideshowArtifactResponse" }, "revision": { "$ref": "#/components/schemas/SlideshowRevisionResponse" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Undo the newest effective slideshow edit by applying its stored inverse operations as a new revision. Pass the current expectedRevision and an Idempotency-Key; undo never rewrites or removes the original history.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UndoSlideshowBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.undoSlideshow({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n contentItemId: process.env.OCTOSPARK_CONTENT_ITEM_ID ?? \"contentItemId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.undo_slideshow(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n contentItemId=os.environ.get(\"OCTOSPARK_CONTENT_ITEM_ID\", \"contentItemId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows undo-slideshow \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"contentItemId\":\"contentItemId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let content_item_id = env::var(\"OCTOSPARK_CONTENT_ITEM_ID\").unwrap_or_else(|_| \"contentItemId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/{}/undo\", base_url.trim_end_matches('/'), team_id, content_item_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final contentItemId = Platform.environment['OCTOSPARK_CONTENT_ITEM_ID'] ?? 'contentItemId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/$contentItemId/undo';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Undo slideshow", "x-displayName": "Undo slideshow" } }, "/v1/teams/{teamId}/content/slideshows/drafts": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.createSlideshowDraft", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "contentItemId", "teamId", "sourceContentItemId", "title", "status", "payloadId", "revision", "creativeHash", "currentCreativeHash", "renderedCreativeHash", "renderFresh", "activeRun", "latestRun", "latestRenderJob", "project", "assetRefs", "links" ], "properties": { "contentItemId": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "sourceContentItemId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "payloadId": { "$ref": "#/components/schemas/UUID" }, "revision": { "$ref": "#/components/schemas/Int" }, "creativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currentCreativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "renderedCreativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "renderFresh": { "type": "boolean" }, "browserPreviewUrl": { "type": "string" }, "previewCreativeHash": { "type": "string" }, "activeRun": { "anyOf": [ { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "latestRun": { "anyOf": [ { "type": "object", "required": [ "id", "status", "errorCode", "diagnostics" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ], "description": "The most recent agent run whatever its outcome, so a failure is visible without having kept its run id." }, "latestRenderJob": { "anyOf": [ { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "project": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowProjectV1" }, { "type": "null" } ] }, "assetRefs": { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, "links": { "type": "object", "required": [ "self", "revisions", "latestRenderJob" ], "properties": { "self": { "type": "string" }, "revisions": { "type": "string" }, "latestRenderJob": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create a slideshow from a minimal description instead of a full project document. Send just the slide text - `{\"slides\":[{\"text\":\"...\"},{\"text\":\"...\"}]}` is a complete request - and the renderer runtime, source bundle, output dimensions, caption styling and layout are supplied for you. Use this to author a deck deterministically; use the generations endpoint when you want the agent to write it from a prompt.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSlideshowDraftBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.createSlideshowDraft({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.create_slideshow_draft(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows create-slideshow-draft \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/drafts\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/drafts';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create slideshow draft", "x-displayName": "Create slideshow draft" } }, "/v1/teams/{teamId}/content/slideshows/generations": { "post": { "tags": [ "Slideshows" ], "operationId": "slideshows.createSlideshowGeneration", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "required": true, "description": "a string at most 200 character(s) long" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "contentItemId", "kind", "status", "targetSlideId", "regenerationScope", "baseRevision", "resultRevision", "workflowId", "renderJobId", "outputAssetId", "errorCode", "diagnostics", "pauseReason", "maxSpendDecimillicents", "spentDecimillicents", "activeDurationMs", "links" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "generation", "slide_regeneration", "edit" ] }, "status": { "type": "string" }, "targetSlideId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "regenerationScope": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowRegenerationScope" }, { "type": "null" } ] }, "baseRevision": { "$ref": "#/components/schemas/Int" }, "resultRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "workflowId": { "type": "string" }, "renderJobId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "outputAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pauseReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSpendDecimillicents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spentDecimillicents": { "type": "number" }, "activeDurationMs": { "type": "number" }, "links": { "type": "object", "required": [ "self", "events", "slideshow" ], "properties": { "self": { "type": "string" }, "events": { "type": "string" }, "slideshow": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Start an agentic slideshow generation from a natural-language prompt. The worker may search team assets, approved same-team references, Pinterest, or image generation tools, so the run is asynchronous and tool usage may spend credits; follow the returned run or event links until it completes. Send an Idempotency-Key so an exact retry cannot create a second run.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateSlideshowBody" } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.slideshows.createSlideshowGeneration({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.slideshows.create_slideshow_generation(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark slideshows create-slideshow-generation \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/content/slideshows/generations\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/content/slideshows/generations';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create slideshow generation", "x-displayName": "Create slideshow generation" } }, "/v1/teams/{teamId}/folders": { "get": { "tags": [ "Folders" ], "operationId": "folders.listFolders", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "parentId", "name", "depth", "assetCount", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "parentId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "name": { "type": "string" }, "depth": { "type": "number" }, "assetCount": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List all asset folders for a team, including their hierarchy via parent ids. Use the returned folder ids to filter listAssets or as targets for moveAssets and createFolder.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.folders.listFolders({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.folders.list_folders(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark folders list-folders \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/folders\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/folders';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List folders", "x-displayName": "List folders" }, "post": { "tags": [ "Folders" ], "operationId": "folders.createFolder", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "parentId", "name", "depth", "assetCount", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "parentId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "name": { "type": "string" }, "depth": { "type": "number" }, "assetCount": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create an asset folder, optionally nested under a parentId (omit or pass null for a root-level folder). Returns the new folder; place assets into it with moveAssets.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "a string at most 128 character(s) long", "title": "maxLength(128)", "minLength": 1, "maxLength": 128 }, "parentId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ], "description": "Parent folder id; null or omitted creates the folder at the root." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.folders.createFolder({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.folders.create_folder(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark folders create-folder \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/folders\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/folders';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create folder", "x-displayName": "Create folder" } }, "/v1/teams/{teamId}/folders/{folderId}": { "patch": { "tags": [ "Folders" ], "operationId": "folders.updateFolder", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "folderId", "in": "path", "schema": { "type": "string", "description": "Media-library folder id (UUID), as returned by the list folders endpoint." }, "required": true, "description": "Media-library folder id (UUID), as returned by the list folders endpoint." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "parentId", "name", "depth", "assetCount", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "parentId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "name": { "type": "string" }, "depth": { "type": "number" }, "assetCount": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Rename a folder and/or move it in the hierarchy: a present parentId moves it (null means move to root), an absent parentId leaves placement unchanged. Use moveAssets to move the assets themselves.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string", "description": "a string at most 128 character(s) long", "title": "maxLength(128)", "minLength": 1, "maxLength": 128 }, "parentId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ], "description": "New parent folder id: present means move (null moves to root), absent leaves placement unchanged." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.folders.updateFolder({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n folderId: process.env.OCTOSPARK_FOLDER_ID ?? \"folderId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.folders.update_folder(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n folderId=os.environ.get(\"OCTOSPARK_FOLDER_ID\", \"folderId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark folders update-folder \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"folderId\":\"folderId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let folder_id = env::var(\"OCTOSPARK_FOLDER_ID\").unwrap_or_else(|_| \"folderId\".to_string());\n let url = format!(\"{}/v1/teams/{}/folders/{}\", base_url.trim_end_matches('/'), team_id, folder_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final folderId = Platform.environment['OCTOSPARK_FOLDER_ID'] ?? 'folderId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/folders/$folderId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Update folder", "x-displayName": "Update folder" }, "delete": { "tags": [ "Folders" ], "operationId": "folders.removeFolder", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "folderId", "in": "path", "schema": { "type": "string", "description": "Media-library folder id (UUID), as returned by the list folders endpoint." }, "required": true, "description": "Media-library folder id (UUID), as returned by the list folders endpoint." }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "delete_contents", "move_to_parent" ], "description": "What happens to the folder contents: delete_contents soft-deletes every asset and subfolder, move_to_parent reparents them before removing the folder.", "examples": [ "move_to_parent" ] }, "required": true, "description": "What happens to the folder contents: delete_contents soft-deletes every asset and subfolder, move_to_parent reparents them before removing the folder." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "mode", "deletedAssetCount", "deletedFolderCount" ], "properties": { "mode": { "type": "string", "enum": [ "delete_contents" ] }, "deletedAssetCount": { "type": "number" }, "deletedFolderCount": { "type": "number" } }, "additionalProperties": false }, { "type": "object", "required": [ "mode", "movedFolderCount", "movedAssetCount" ], "properties": { "mode": { "type": "string", "enum": [ "move_to_parent" ] }, "movedFolderCount": { "type": "number" }, "movedAssetCount": { "type": "number" } }, "additionalProperties": false } ] } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Conflict" }, { "$ref": "#/components/schemas/FolderDeleteBlocked" } ] } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Delete a folder using the required mode query param: delete_contents removes the folder with its assets and subfolders, move_to_parent relocates contents up one level first. Returns counts of what was deleted or moved. Responds 409 (with the blocking asset ids) when deletion would remove assets attached to scheduled posts.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.folders.removeFolder({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n folderId: process.env.OCTOSPARK_FOLDER_ID ?? \"folderId\",\n query: {\n \"mode\": process.env.OCTOSPARK_MODE ?? \"mode\",\n },\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.folders.remove_folder(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n folderId=os.environ.get(\"OCTOSPARK_FOLDER_ID\", \"folderId\"),\n query={\n \"mode\": os.environ.get(\"OCTOSPARK_MODE\", \"mode\"),\n }\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark folders remove-folder \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"folderId\":\"folderId\"},\"query\":{\"mode\":\"mode\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let folder_id = env::var(\"OCTOSPARK_FOLDER_ID\").unwrap_or_else(|_| \"folderId\".to_string());\n let mode = env::var(\"OCTOSPARK_MODE\").unwrap_or_else(|_| \"mode\".to_string());\n let url = format!(\"{}/v1/teams/{}/folders/{}\", base_url.trim_end_matches('/'), team_id, folder_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let query = [(\"mode\", mode.as_str())];\n request = request.query(&query);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final folderId = Platform.environment['OCTOSPARK_FOLDER_ID'] ?? 'folderId';\n final mode = Platform.environment['OCTOSPARK_MODE'] ?? 'mode';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/folders/$folderId';\n final uri = Uri.parse(url).replace(queryParameters: {\n 'mode': mode,\n });\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete folder", "x-displayName": "Delete folder" } }, "/v1/teams/{teamId}/media-creation/runs/{runId}/editor": { "get": { "tags": [ "Media creation" ], "operationId": "mediaCreation.getMemeEditorForRun", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "runId", "in": "path", "schema": { "type": "string", "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": true, "description": "Artifact run id (UUID), as returned by slideshow generation or slide regeneration." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "runId", "type", "request" ], "properties": { "runId": { "$ref": "#/components/schemas/UUID" }, "type": { "type": "string", "enum": [ "image_meme" ] }, "request": { "type": "object", "required": [ "templateAssetId", "title", "aspectRatio" ], "properties": { "templateAssetId": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "aspectRatio": { "type": "string", "enum": [ "original", "9:16", "16:9", "1:1", "4:5" ], "description": "Output proportions. Use original to preserve the template canvas and caption zones." }, "captions": { "type": "array", "items": { "type": "object", "required": [ "id", "text", "x", "y", "width", "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "text": { "type": "string", "description": "a string at most 2000 character(s) long", "title": "maxLength(2000)", "maxLength": 2000 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "maxItems": 20 } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "runId", "type", "request" ], "properties": { "runId": { "$ref": "#/components/schemas/UUID" }, "type": { "type": "string", "enum": [ "green_screen_meme" ] }, "request": { "type": "object", "required": [ "templateAssetId", "backgroundAssetId", "title", "aspectRatio", "captions", "audio", "chromaKey" ], "properties": { "templateAssetId": { "$ref": "#/components/schemas/UUID" }, "backgroundAssetId": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ], "description": "Output proportions used to size the background and composition." }, "captions": { "type": "array", "items": { "type": "object", "required": [ "id", "text", "x", "y", "width", "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "text": { "type": "string", "description": "a string at most 2000 character(s) long", "title": "maxLength(2000)", "maxLength": 2000 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "maxItems": 20 }, "audio": { "type": "object", "required": [ "mode", "volume" ], "properties": { "mode": { "type": "string", "enum": [ "original", "mute" ] }, "volume": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false, "description": "Choose whether to keep or mute the template audio and its playback volume from zero to one." }, "chromaKey": { "type": "object", "required": [ "keyColor", "similarity", "blend", "despill", "version" ], "properties": { "keyColor": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}$", "pattern": "^#[0-9a-fA-F]{6}$" }, "similarity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "blend": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "despill": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "version": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, "confidence": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false, "description": "Saved template calibration for removing the screen colour and reducing colour spill. Editors obtain this from template metadata automatically." } }, "additionalProperties": false } }, "additionalProperties": false } ] } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Recover the frozen image-meme or green-screen editor request for an eligible run, including its captions, aspect ratio, background and audio settings. Available for live team content and media within 365 days, even before the first run bundle is saved. Returns only validated editor fields and does not spend credits.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.mediaCreation.getMemeEditorForRun({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n runId: process.env.OCTOSPARK_RUN_ID ?? \"runId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.media_creation.get_meme_editor_for_run(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n runId=os.environ.get(\"OCTOSPARK_RUN_ID\", \"runId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark media-creation get-meme-editor-for-run \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"runId\":\"runId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let run_id = env::var(\"OCTOSPARK_RUN_ID\").unwrap_or_else(|_| \"runId\".to_string());\n let url = format!(\"{}/v1/teams/{}/media-creation/runs/{}/editor\", base_url.trim_end_matches('/'), team_id, run_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final runId = Platform.environment['OCTOSPARK_RUN_ID'] ?? 'runId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/media-creation/runs/$runId/editor';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Meme editor for run", "x-displayName": "Meme editor for run" } }, "/v1/teams/{teamId}/personas": { "get": { "tags": [ "Personas" ], "operationId": "personas.listPersonas", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor returned by a previous persona list response to fetch the next page." }, "required": false, "description": "Cursor returned by a previous persona list response to fetch the next page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "a string to be decoded into a number" }, "required": false, "description": "a string to be decoded into a number" }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction for persona creation time." }, "required": false, "description": "Sort direction for persona creation time." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "origin", "displayName", "dateOfBirth", "biography", "careerExperiences", "avatarAttributes", "selectedElevenLabsVoiceId", "revision", "archivedAt", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "origin": { "type": "string", "enum": [ "real_person", "synthetic_person" ] }, "displayName": { "type": "string" }, "dateOfBirth": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "biography": { "type": "string" }, "careerExperiences": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "summary", "isCurrent" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "organization": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "industry": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "summary": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "startedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "isCurrent": { "type": "boolean", "description": "Whether this experience is ongoing. Ongoing experiences must not include an end date." } }, "additionalProperties": false }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "maxItems": 100 }, "avatarAttributes": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "type": "string" } }, "selectedElevenLabsVoiceId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "revision": { "$ref": "#/components/schemas/Int" }, "archivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List active team personas with cursor pagination for persona pickers and management.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.listPersonas({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.list_personas(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas list-personas \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List personas", "x-displayName": "List personas" }, "post": { "tags": [ "Personas" ], "operationId": "personas.createPersona", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "Reuse this key and the original body after a lost response. Changed requests return 409. For generated creation, this header must match the payload idempotencyKey.", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "required": false, "description": "Reuse this key and the original body after a lost response. Changed requests return 409. For generated creation, this header must match the payload idempotencyKey." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "origin", "displayName", "dateOfBirth", "biography", "careerExperiences", "avatarAttributes", "selectedElevenLabsVoiceId", "revision", "archivedAt", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "origin": { "type": "string", "enum": [ "real_person", "synthetic_person" ] }, "displayName": { "type": "string" }, "dateOfBirth": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "biography": { "type": "string" }, "careerExperiences": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "summary", "isCurrent" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "organization": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "industry": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "summary": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "startedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "isCurrent": { "type": "boolean", "description": "Whether this experience is ongoing. Ongoing experiences must not include an end date." } }, "additionalProperties": false }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "maxItems": 100 }, "avatarAttributes": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "type": "string" } }, "selectedElevenLabsVoiceId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "revision": { "$ref": "#/components/schemas/Int" }, "archivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create an imported or generated persona and retain its original references. Generated creation uses the payload idempotencyKey; imported creation can send Idempotency-Key. Reuse the original body after a lost response to resume setup or return the same current persona without another identity pack. Changed requests return 409; archived or deleted personas return 404.", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "mode", "origin", "profile", "idempotencyKey" ], "properties": { "mode": { "type": "string", "enum": [ "generated" ] }, "origin": { "type": "string", "enum": [ "synthetic_person" ] }, "profile": { "type": "object", "required": [ "displayName", "dateOfBirth", "biography", "careerExperiences", "avatarAttributes" ], "properties": { "displayName": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "dateOfBirth": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "biography": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "careerExperiences": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "summary", "isCurrent" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "organization": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "industry": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "summary": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "startedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "isCurrent": { "type": "boolean", "description": "Whether this experience is ongoing. Ongoing experiences must not include an end date." } }, "additionalProperties": false }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "maxItems": 100 }, "avatarAttributes": { "type": "object", "required": [ "gender", "skinTone", "skinClarity", "faceShape", "jawline", "cheekbones", "chin", "hairStyle", "hairColor", "hairLength", "hairTexture", "eyeShape", "eyeColor", "eyebrowShape", "noseShape", "earShape", "lipShape", "bodyType", "heightImpression", "shoulderWidth", "styleAesthetic" ], "properties": { "gender": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "skinTone": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "skinClarity": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "faceShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "jawline": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "cheekbones": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "chin": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairStyle": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairColor": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairLength": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairTexture": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "eyeShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "eyeColor": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "eyebrowShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "noseShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "earShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "lipShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "bodyType": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "heightImpression": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "shoulderWidth": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "styleAesthetic": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "moles": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "underEyes": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "freckles": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "dimples": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairHighlights": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "tattoos": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "beardStyle": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "piercings": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "glasses": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "defaultJewelry": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "defaultHeadwear": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "scars": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "birthmarks": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "teethGap": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 } }, "additionalProperties": false, "description": "Visual identity traits used to keep generated persona media consistent. Omitted optional modifiers are stored as none." } }, "additionalProperties": false }, "selectedElevenLabsVoiceId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "referenceAssets": { "type": "array", "items": { "type": "object", "required": [ "assetId", "assignmentSource" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "assignmentSource": { "type": "string", "enum": [ "imported", "generated", "manual", "agent" ] }, "identityShot": { "type": "string", "enum": [ "character_sheet", "front_neutral", "three_quarter_left", "three_quarter_right", "profile_left", "profile_right", "front_smile", "front_talking", "full_body_back", "waist_up_hands", "full_body_front", "full_body_three_quarter" ] }, "portrayedAge": { "$ref": "#/components/schemas/Int", "description": "a number between 15 and 75", "title": "between(15, 75)", "minimum": 15, "maximum": 75 }, "cameraView": { "type": "string", "enum": [ "front", "three_quarter", "profile", "back" ] }, "framing": { "type": "string", "enum": [ "headshot", "portrait", "half_body", "full_body" ] }, "isReference": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "sortOrder": { "$ref": "#/components/schemas/Int" } }, "additionalProperties": false }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "maxItems": 100 }, "modelId": { "type": "string", "description": "Persona image requests use google/gemini-3.1-pro-image. Omit modelId or provide that value. New requests for another model are rejected before setup or generation; matching accepted requests retain their original replay behaviour.", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "idempotencyKey": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 } }, "additionalProperties": false }, { "type": "object", "required": [ "mode", "origin", "profile", "referenceAssets" ], "properties": { "mode": { "type": "string", "enum": [ "imported" ] }, "origin": { "type": "string", "enum": [ "real_person", "synthetic_person" ] }, "profile": { "type": "object", "required": [ "displayName", "dateOfBirth", "biography", "careerExperiences", "avatarAttributes" ], "properties": { "displayName": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "dateOfBirth": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "biography": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "careerExperiences": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "summary", "isCurrent" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "organization": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "industry": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "summary": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "startedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "isCurrent": { "type": "boolean", "description": "Whether this experience is ongoing. Ongoing experiences must not include an end date." } }, "additionalProperties": false }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "maxItems": 100 }, "avatarAttributes": { "type": "object", "required": [ "gender", "skinTone", "skinClarity", "faceShape", "jawline", "cheekbones", "chin", "hairStyle", "hairColor", "hairLength", "hairTexture", "eyeShape", "eyeColor", "eyebrowShape", "noseShape", "earShape", "lipShape", "bodyType", "heightImpression", "shoulderWidth", "styleAesthetic" ], "properties": { "gender": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "skinTone": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "skinClarity": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "faceShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "jawline": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "cheekbones": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "chin": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairStyle": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairColor": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairLength": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairTexture": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "eyeShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "eyeColor": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "eyebrowShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "noseShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "earShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "lipShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "bodyType": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "heightImpression": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "shoulderWidth": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "styleAesthetic": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "moles": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "underEyes": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "freckles": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "dimples": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairHighlights": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "tattoos": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "beardStyle": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "piercings": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "glasses": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "defaultJewelry": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "defaultHeadwear": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "scars": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "birthmarks": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "teethGap": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 } }, "additionalProperties": false, "description": "Visual identity traits used to keep generated persona media consistent. Omitted optional modifiers are stored as none." } }, "additionalProperties": false }, "selectedElevenLabsVoiceId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "referenceAssets": { "type": "array", "items": { "type": "object", "required": [ "assetId", "assignmentSource" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "assignmentSource": { "type": "string", "enum": [ "imported", "generated", "manual", "agent" ] }, "identityShot": { "type": "string", "enum": [ "character_sheet", "front_neutral", "three_quarter_left", "three_quarter_right", "profile_left", "profile_right", "front_smile", "front_talking", "full_body_back", "waist_up_hands", "full_body_front", "full_body_three_quarter" ] }, "portrayedAge": { "$ref": "#/components/schemas/Int", "description": "a number between 15 and 75", "title": "between(15, 75)", "minimum": 15, "maximum": 75 }, "cameraView": { "type": "string", "enum": [ "front", "three_quarter", "profile", "back" ] }, "framing": { "type": "string", "enum": [ "headshot", "portrait", "half_body", "full_body" ] }, "isReference": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "sortOrder": { "$ref": "#/components/schemas/Int" } }, "additionalProperties": false }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "minItems": 1, "maxItems": 100 } }, "additionalProperties": false } ] } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.createPersona({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.create_persona(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas create-persona \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create persona", "x-displayName": "Create persona" } }, "/v1/teams/{teamId}/personas/{personaId}": { "get": { "tags": [ "Personas" ], "operationId": "personas.getPersona", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "personaId", "in": "path", "schema": { "type": "string", "description": "Persona id (UUID), returned by list or create persona." }, "required": true, "description": "Persona id (UUID), returned by list or create persona." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "origin", "displayName", "dateOfBirth", "biography", "careerExperiences", "avatarAttributes", "selectedElevenLabsVoiceId", "revision", "archivedAt", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "origin": { "type": "string", "enum": [ "real_person", "synthetic_person" ] }, "displayName": { "type": "string" }, "dateOfBirth": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "biography": { "type": "string" }, "careerExperiences": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "summary", "isCurrent" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "organization": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "industry": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "summary": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "startedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "isCurrent": { "type": "boolean", "description": "Whether this experience is ongoing. Ongoing experiences must not include an end date." } }, "additionalProperties": false }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "maxItems": 100 }, "avatarAttributes": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "type": "string" } }, "selectedElevenLabsVoiceId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "revision": { "$ref": "#/components/schemas/Int" }, "archivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Fetch one persona with full avatar attributes and career experiences.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.getPersona({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n personaId: process.env.OCTOSPARK_PERSONA_ID ?? \"personaId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.get_persona(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n personaId=os.environ.get(\"OCTOSPARK_PERSONA_ID\", \"personaId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas get-persona \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"personaId\":\"personaId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let persona_id = env::var(\"OCTOSPARK_PERSONA_ID\").unwrap_or_else(|_| \"personaId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/{}\", base_url.trim_end_matches('/'), team_id, persona_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final personaId = Platform.environment['OCTOSPARK_PERSONA_ID'] ?? 'personaId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/$personaId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Persona", "x-displayName": "Persona" }, "patch": { "tags": [ "Personas" ], "operationId": "personas.updatePersona", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "personaId", "in": "path", "schema": { "type": "string", "description": "Persona id (UUID), returned by list or create persona." }, "required": true, "description": "Persona id (UUID), returned by list or create persona." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "origin", "displayName", "dateOfBirth", "biography", "careerExperiences", "avatarAttributes", "selectedElevenLabsVoiceId", "revision", "archivedAt", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "origin": { "type": "string", "enum": [ "real_person", "synthetic_person" ] }, "displayName": { "type": "string" }, "dateOfBirth": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "biography": { "type": "string" }, "careerExperiences": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "summary", "isCurrent" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "organization": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "industry": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "summary": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "startedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "isCurrent": { "type": "boolean", "description": "Whether this experience is ongoing. Ongoing experiences must not include an end date." } }, "additionalProperties": false }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "maxItems": 100 }, "avatarAttributes": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "type": "string" } }, "selectedElevenLabsVoiceId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "revision": { "$ref": "#/components/schemas/Int" }, "archivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Update a mutable persona profile and atomically increment its revision.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "displayName": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "dateOfBirth": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "biography": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "careerExperiences": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "summary", "isCurrent" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "organization": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "industry": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "summary": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "startedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "isCurrent": { "type": "boolean", "description": "Whether this experience is ongoing. Ongoing experiences must not include an end date." } }, "additionalProperties": false }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "maxItems": 100 }, "avatarAttributes": { "type": "object", "required": [ "gender", "skinTone", "skinClarity", "faceShape", "jawline", "cheekbones", "chin", "hairStyle", "hairColor", "hairLength", "hairTexture", "eyeShape", "eyeColor", "eyebrowShape", "noseShape", "earShape", "lipShape", "bodyType", "heightImpression", "shoulderWidth", "styleAesthetic" ], "properties": { "gender": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "skinTone": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "skinClarity": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "faceShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "jawline": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "cheekbones": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "chin": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairStyle": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairColor": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairLength": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairTexture": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "eyeShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "eyeColor": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "eyebrowShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "noseShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "earShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "lipShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "bodyType": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "heightImpression": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "shoulderWidth": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "styleAesthetic": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "moles": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "underEyes": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "freckles": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "dimples": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairHighlights": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "tattoos": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "beardStyle": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "piercings": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "glasses": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "defaultJewelry": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "defaultHeadwear": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "scars": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "birthmarks": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "teethGap": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 } }, "additionalProperties": false, "description": "Visual identity traits used to keep generated persona media consistent. Omitted optional modifiers are stored as none." }, "selectedElevenLabsVoiceId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ], "description": "Reusable ElevenLabs voice selection. Send null to clear the current voice." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.updatePersona({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n personaId: process.env.OCTOSPARK_PERSONA_ID ?? \"personaId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.update_persona(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n personaId=os.environ.get(\"OCTOSPARK_PERSONA_ID\", \"personaId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas update-persona \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"personaId\":\"personaId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let persona_id = env::var(\"OCTOSPARK_PERSONA_ID\").unwrap_or_else(|_| \"personaId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/{}\", base_url.trim_end_matches('/'), team_id, persona_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final personaId = Platform.environment['OCTOSPARK_PERSONA_ID'] ?? 'personaId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/$personaId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Update persona", "x-displayName": "Update persona" }, "delete": { "tags": [ "Personas" ], "operationId": "personas.archivePersona", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "personaId", "in": "path", "schema": { "type": "string", "description": "Persona id (UUID), returned by list or create persona." }, "required": true, "description": "Persona id (UUID), returned by list or create persona." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Archive a persona while preserving its historic media and content.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.archivePersona({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n personaId: process.env.OCTOSPARK_PERSONA_ID ?? \"personaId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.archive_persona(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n personaId=os.environ.get(\"OCTOSPARK_PERSONA_ID\", \"personaId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas archive-persona \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"personaId\":\"personaId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let persona_id = env::var(\"OCTOSPARK_PERSONA_ID\").unwrap_or_else(|_| \"personaId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/{}\", base_url.trim_end_matches('/'), team_id, persona_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final personaId = Platform.environment['OCTOSPARK_PERSONA_ID'] ?? 'personaId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/$personaId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Archive persona", "x-displayName": "Archive persona" } }, "/v1/teams/{teamId}/personas/{personaId}/character-sheet": { "post": { "tags": [ "Personas" ], "operationId": "personas.createPersonaCharacterSheet", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "personaId", "in": "path", "schema": { "type": "string", "description": "Persona id (UUID), returned by list or create persona." }, "required": true, "description": "Persona id (UUID), returned by list or create persona." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "assetId", "sourceAssetIds", "width", "height" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "sourceAssetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "width": { "$ref": "#/components/schemas/Int" }, "height": { "$ref": "#/components/schemas/Int" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Assemble every selected original photograph into a single deterministic likeness sheet and retain all originals.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "assetIds", "portrayedAge" ], "properties": { "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "minItems": 1, "maxItems": 100 }, "portrayedAge": { "$ref": "#/components/schemas/Int", "description": "a number between 0 and 120", "title": "between(0, 120)", "minimum": 0, "maximum": 120 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.createPersonaCharacterSheet({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n personaId: process.env.OCTOSPARK_PERSONA_ID ?? \"personaId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.create_persona_character_sheet(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n personaId=os.environ.get(\"OCTOSPARK_PERSONA_ID\", \"personaId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas create-persona-character-sheet \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"personaId\":\"personaId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let persona_id = env::var(\"OCTOSPARK_PERSONA_ID\").unwrap_or_else(|_| \"personaId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/{}/character-sheet\", base_url.trim_end_matches('/'), team_id, persona_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final personaId = Platform.environment['OCTOSPARK_PERSONA_ID'] ?? 'personaId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/$personaId/character-sheet';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create persona character sheet", "x-displayName": "Create persona character sheet" } }, "/v1/teams/{teamId}/personas/{personaId}/life-events": { "get": { "tags": [ "Personas" ], "operationId": "personas.listPersonaLifeEvents", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "personaId", "in": "path", "schema": { "type": "string", "description": "Persona id (UUID), returned by list or create persona." }, "required": true, "description": "Persona id (UUID), returned by list or create persona." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "personaId", "category", "title", "story", "occurredAt", "endedAt", "location", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "personaId": { "$ref": "#/components/schemas/UUID" }, "category": { "type": "string" }, "title": { "type": "string" }, "story": { "type": "string" }, "occurredAt": { "type": "string" }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the chronological life-event narrative for a persona.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.listPersonaLifeEvents({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n personaId: process.env.OCTOSPARK_PERSONA_ID ?? \"personaId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.list_persona_life_events(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n personaId=os.environ.get(\"OCTOSPARK_PERSONA_ID\", \"personaId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas list-persona-life-events \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"personaId\":\"personaId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let persona_id = env::var(\"OCTOSPARK_PERSONA_ID\").unwrap_or_else(|_| \"personaId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/{}/life-events\", base_url.trim_end_matches('/'), team_id, persona_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final personaId = Platform.environment['OCTOSPARK_PERSONA_ID'] ?? 'personaId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/$personaId/life-events';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List persona life events", "x-displayName": "List persona life events" }, "post": { "tags": [ "Personas" ], "operationId": "personas.createPersonaLifeEvent", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "personaId", "in": "path", "schema": { "type": "string", "description": "Persona id (UUID), returned by list or create persona." }, "required": true, "description": "Persona id (UUID), returned by list or create persona." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "personaId", "category", "title", "story", "occurredAt", "endedAt", "location", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "personaId": { "$ref": "#/components/schemas/UUID" }, "category": { "type": "string" }, "title": { "type": "string" }, "story": { "type": "string" }, "occurredAt": { "type": "string" }, "endedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create a life event for persona grounding and future content prompts.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "category", "title", "story", "occurredAt" ], "properties": { "category": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "title": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "story": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "occurredAt": { "$ref": "#/components/schemas/DateTimeUtc" }, "endedAt": { "$ref": "#/components/schemas/DateTimeUtc" }, "location": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.createPersonaLifeEvent({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n personaId: process.env.OCTOSPARK_PERSONA_ID ?? \"personaId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.create_persona_life_event(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n personaId=os.environ.get(\"OCTOSPARK_PERSONA_ID\", \"personaId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas create-persona-life-event \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"personaId\":\"personaId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let persona_id = env::var(\"OCTOSPARK_PERSONA_ID\").unwrap_or_else(|_| \"personaId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/{}/life-events\", base_url.trim_end_matches('/'), team_id, persona_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final personaId = Platform.environment['OCTOSPARK_PERSONA_ID'] ?? 'personaId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/$personaId/life-events';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create persona life event", "x-displayName": "Create persona life event" } }, "/v1/teams/{teamId}/personas/{personaId}/life-events/{lifeEventId}": { "delete": { "tags": [ "Personas" ], "operationId": "personas.deletePersonaLifeEvent", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "personaId", "in": "path", "schema": { "type": "string", "description": "Persona id (UUID), returned by list or create persona." }, "required": true, "description": "Persona id (UUID), returned by list or create persona." }, { "name": "lifeEventId", "in": "path", "schema": { "type": "string", "description": "Persona life-event id returned by create or list." }, "required": true, "description": "Persona life-event id returned by create or list." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Permanently delete one persona life event when its narrative is no longer suitable for future persona prompts.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.deletePersonaLifeEvent({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n personaId: process.env.OCTOSPARK_PERSONA_ID ?? \"personaId\",\n lifeEventId: process.env.OCTOSPARK_LIFE_EVENT_ID ?? \"lifeEventId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.delete_persona_life_event(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n personaId=os.environ.get(\"OCTOSPARK_PERSONA_ID\", \"personaId\"),\n lifeEventId=os.environ.get(\"OCTOSPARK_LIFE_EVENT_ID\", \"lifeEventId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas delete-persona-life-event \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"personaId\":\"personaId\",\"lifeEventId\":\"lifeEventId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let persona_id = env::var(\"OCTOSPARK_PERSONA_ID\").unwrap_or_else(|_| \"personaId\".to_string());\n let life_event_id = env::var(\"OCTOSPARK_LIFE_EVENT_ID\").unwrap_or_else(|_| \"lifeEventId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/{}/life-events/{}\", base_url.trim_end_matches('/'), team_id, persona_id, life_event_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final personaId = Platform.environment['OCTOSPARK_PERSONA_ID'] ?? 'personaId';\n final lifeEventId = Platform.environment['OCTOSPARK_LIFE_EVENT_ID'] ?? 'lifeEventId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/$personaId/life-events/$lifeEventId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete persona life event", "x-displayName": "Delete persona life event" } }, "/v1/teams/{teamId}/personas/{personaId}/media": { "get": { "tags": [ "Personas" ], "operationId": "personas.listPersonaMedia", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "personaId", "in": "path", "schema": { "type": "string", "description": "Persona id (UUID), returned by list or create persona." }, "required": true, "description": "Persona id (UUID), returned by list or create persona." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor returned by a previous persona media response." }, "required": false, "description": "Cursor returned by a previous persona media response." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "a string to be decoded into a number" }, "required": false, "description": "a string to be decoded into a number" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "personaId", "assetId", "identityShot", "assignmentSource", "generationId", "portrayedAge", "cameraView", "framing", "isReference", "isPrimary", "sortOrder", "promotedAt", "createdAt", "updatedAt" ], "properties": { "personaId": { "$ref": "#/components/schemas/UUID" }, "assetId": { "$ref": "#/components/schemas/UUID" }, "identityShot": { "anyOf": [ { "type": "string", "enum": [ "character_sheet", "front_neutral", "three_quarter_left", "three_quarter_right", "profile_left", "profile_right", "front_smile", "front_talking", "full_body_back", "waist_up_hands", "full_body_front", "full_body_three_quarter" ] }, { "type": "null" } ] }, "assignmentSource": { "type": "string", "enum": [ "imported", "generated", "manual", "agent" ] }, "generationId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "portrayedAge": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "cameraView": { "anyOf": [ { "type": "string", "enum": [ "front", "three_quarter", "profile", "back" ] }, { "type": "null" } ] }, "framing": { "anyOf": [ { "type": "string", "enum": [ "headshot", "portrait", "half_body", "full_body" ] }, { "type": "null" } ] }, "isReference": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "sortOrder": { "$ref": "#/components/schemas/Int" }, "promotedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List media assigned to a persona with cursor pagination for recent-media hydration.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.listPersonaMedia({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n personaId: process.env.OCTOSPARK_PERSONA_ID ?? \"personaId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.list_persona_media(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n personaId=os.environ.get(\"OCTOSPARK_PERSONA_ID\", \"personaId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas list-persona-media \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"personaId\":\"personaId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let persona_id = env::var(\"OCTOSPARK_PERSONA_ID\").unwrap_or_else(|_| \"personaId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/{}/media\", base_url.trim_end_matches('/'), team_id, persona_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final personaId = Platform.environment['OCTOSPARK_PERSONA_ID'] ?? 'personaId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/$personaId/media';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List persona media", "x-displayName": "List persona media" } }, "/v1/teams/{teamId}/personas/{personaId}/media/{assetId}/promote": { "post": { "tags": [ "Personas" ], "operationId": "personas.promotePersonaMedia", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "personaId", "in": "path", "schema": { "type": "string", "description": "Persona id (UUID), returned by list or create persona." }, "required": true, "description": "Persona id (UUID), returned by list or create persona." }, { "name": "assetId", "in": "path", "schema": { "type": "string", "description": "Persona-linked media asset id." }, "required": true, "description": "Persona-linked media asset id." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "personaId", "assetId", "identityShot", "assignmentSource", "generationId", "portrayedAge", "cameraView", "framing", "isReference", "isPrimary", "sortOrder", "promotedAt", "createdAt", "updatedAt" ], "properties": { "personaId": { "$ref": "#/components/schemas/UUID" }, "assetId": { "$ref": "#/components/schemas/UUID" }, "identityShot": { "anyOf": [ { "type": "string", "enum": [ "character_sheet", "front_neutral", "three_quarter_left", "three_quarter_right", "profile_left", "profile_right", "front_smile", "front_talking", "full_body_back", "waist_up_hands", "full_body_front", "full_body_three_quarter" ] }, { "type": "null" } ] }, "assignmentSource": { "type": "string", "enum": [ "imported", "generated", "manual", "agent" ] }, "generationId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "portrayedAge": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "cameraView": { "anyOf": [ { "type": "string", "enum": [ "front", "three_quarter", "profile", "back" ] }, { "type": "null" } ] }, "framing": { "anyOf": [ { "type": "string", "enum": [ "headshot", "portrait", "half_body", "full_body" ] }, { "type": "null" } ] }, "isReference": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "sortOrder": { "$ref": "#/components/schemas/Int" }, "promotedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Explicitly promote a generated candidate as the active identity reference for its age, view, and framing slot.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.promotePersonaMedia({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n personaId: process.env.OCTOSPARK_PERSONA_ID ?? \"personaId\",\n assetId: process.env.OCTOSPARK_ASSET_ID ?? \"assetId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.promote_persona_media(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n personaId=os.environ.get(\"OCTOSPARK_PERSONA_ID\", \"personaId\"),\n assetId=os.environ.get(\"OCTOSPARK_ASSET_ID\", \"assetId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas promote-persona-media \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"personaId\":\"personaId\",\"assetId\":\"assetId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let persona_id = env::var(\"OCTOSPARK_PERSONA_ID\").unwrap_or_else(|_| \"personaId\".to_string());\n let asset_id = env::var(\"OCTOSPARK_ASSET_ID\").unwrap_or_else(|_| \"assetId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/{}/media/{}/promote\", base_url.trim_end_matches('/'), team_id, persona_id, asset_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final personaId = Platform.environment['OCTOSPARK_PERSONA_ID'] ?? 'personaId';\n final assetId = Platform.environment['OCTOSPARK_ASSET_ID'] ?? 'assetId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/$personaId/media/$assetId/promote';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.post(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Promote persona media", "x-displayName": "Promote persona media" } }, "/v1/teams/{teamId}/personas/{personaId}/references": { "post": { "tags": [ "Personas" ], "operationId": "personas.assignPersonaReference", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "personaId", "in": "path", "schema": { "type": "string", "description": "Persona id (UUID), returned by list or create persona." }, "required": true, "description": "Persona id (UUID), returned by list or create persona." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "personaId", "assetId", "identityShot", "assignmentSource", "generationId", "portrayedAge", "cameraView", "framing", "isReference", "isPrimary", "sortOrder", "promotedAt", "createdAt", "updatedAt" ], "properties": { "personaId": { "$ref": "#/components/schemas/UUID" }, "assetId": { "$ref": "#/components/schemas/UUID" }, "identityShot": { "anyOf": [ { "type": "string", "enum": [ "character_sheet", "front_neutral", "three_quarter_left", "three_quarter_right", "profile_left", "profile_right", "front_smile", "front_talking", "full_body_back", "waist_up_hands", "full_body_front", "full_body_three_quarter" ] }, { "type": "null" } ] }, "assignmentSource": { "type": "string", "enum": [ "imported", "generated", "manual", "agent" ] }, "generationId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "portrayedAge": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "cameraView": { "anyOf": [ { "type": "string", "enum": [ "front", "three_quarter", "profile", "back" ] }, { "type": "null" } ] }, "framing": { "anyOf": [ { "type": "string", "enum": [ "headshot", "portrait", "half_body", "full_body" ] }, { "type": "null" } ] }, "isReference": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "sortOrder": { "$ref": "#/components/schemas/Int" }, "promotedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Assign a completed team image asset to a guided identity shot and make it the active reference.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "assetId", "identityShot", "portrayedAge" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "identityShot": { "type": "string", "enum": [ "character_sheet", "front_neutral", "three_quarter_left", "three_quarter_right", "profile_left", "profile_right", "front_smile", "front_talking", "full_body_back", "waist_up_hands", "full_body_front", "full_body_three_quarter" ], "description": "Which identity view or character sheet this uploaded image represents, such as a front headshot or left profile. Assigning a new image to an occupied view replaces that view." }, "portrayedAge": { "$ref": "#/components/schemas/Int", "description": "a number between 15 and 75", "title": "between(15, 75)", "minimum": 15, "maximum": 75 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.assignPersonaReference({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n personaId: process.env.OCTOSPARK_PERSONA_ID ?? \"personaId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.assign_persona_reference(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n personaId=os.environ.get(\"OCTOSPARK_PERSONA_ID\", \"personaId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas assign-persona-reference \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"personaId\":\"personaId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let persona_id = env::var(\"OCTOSPARK_PERSONA_ID\").unwrap_or_else(|_| \"personaId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/{}/references\", base_url.trim_end_matches('/'), team_id, persona_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final personaId = Platform.environment['OCTOSPARK_PERSONA_ID'] ?? 'personaId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/$personaId/references';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Assign persona reference", "x-displayName": "Assign persona reference" } }, "/v1/teams/{teamId}/personas/{personaId}/render": { "post": { "tags": [ "Personas" ], "operationId": "personas.renderPersonaView", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "personaId", "in": "path", "schema": { "type": "string", "description": "Persona id (UUID), returned by list or create persona." }, "required": true, "description": "Persona id (UUID), returned by list or create persona." }, { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "description": "Reuse this key and the original body after a lost response. Changed requests return 409. For generated creation, this header must match the payload idempotencyKey.", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "required": false, "description": "Reuse this key and the original body after a lost response. Changed requests return 409. For generated creation, this header must match the payload idempotencyKey." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "organizationId", "sourceSurface", "modelId", "modality", "route", "status", "statusError", "primaryAssetId", "assetIds", "estimatedCostDecimillicents", "actualCostDecimillicents", "callerIdempotencyKey", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "organizationId": { "$ref": "#/components/schemas/UUID" }, "sourceSurface": { "type": "string", "enum": [ "studio", "agent", "editor", "persona" ] }, "modelId": { "type": "string" }, "modality": { "type": "string", "enum": [ "image", "video" ] }, "route": { "type": "string", "enum": [ "openrouter", "fal" ] }, "status": { "type": "string", "enum": [ "queued", "reserved", "running", "rate_limited", "ready", "failed", "cancelled", "skipped_insufficient_credits" ] }, "statusError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "estimatedCostDecimillicents": { "type": "number" }, "actualCostDecimillicents": { "type": "number" }, "callerIdempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Generate one updated persona image using up to three approved identity references. Send Idempotency-Key and reuse the original body after a lost response to return the same generation in any state, preserving its original profile and references. A changed request returns 409. A new key requests another view; the initial identity pack is not rerun.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt", "cameraView", "framing" ], "properties": { "prompt": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "identityShot": { "type": "string", "enum": [ "character_sheet", "front_neutral", "three_quarter_left", "three_quarter_right", "profile_left", "profile_right", "front_smile", "front_talking", "full_body_back", "waist_up_hands", "full_body_front", "full_body_three_quarter" ], "description": "The identity-pack view to generate. Omit this to render a standalone persona image without filling a pack view." }, "draftProfile": { "type": "object", "required": [ "displayName", "dateOfBirth", "biography", "careerExperiences", "avatarAttributes" ], "properties": { "displayName": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "dateOfBirth": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "biography": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "careerExperiences": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "summary", "isCurrent" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "organization": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "industry": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "summary": { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, "startedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endedAt": { "type": "string", "description": "a string matching the pattern ^\\d{4}-\\d{2}-\\d{2}$", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "isCurrent": { "type": "boolean", "description": "Whether this experience is ongoing. Ongoing experiences must not include an end date." } }, "additionalProperties": false }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "maxItems": 100 }, "avatarAttributes": { "type": "object", "required": [ "gender", "skinTone", "skinClarity", "faceShape", "jawline", "cheekbones", "chin", "hairStyle", "hairColor", "hairLength", "hairTexture", "eyeShape", "eyeColor", "eyebrowShape", "noseShape", "earShape", "lipShape", "bodyType", "heightImpression", "shoulderWidth", "styleAesthetic" ], "properties": { "gender": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "skinTone": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "skinClarity": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "faceShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "jawline": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "cheekbones": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "chin": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairStyle": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairColor": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairLength": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairTexture": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "eyeShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "eyeColor": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "eyebrowShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "noseShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "earShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "lipShape": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "bodyType": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "heightImpression": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "shoulderWidth": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "styleAesthetic": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "moles": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "underEyes": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "freckles": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "dimples": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "hairHighlights": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "tattoos": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "beardStyle": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "piercings": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "glasses": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "defaultJewelry": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "defaultHeadwear": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "scars": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "birthmarks": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "teethGap": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 } }, "additionalProperties": false, "description": "Visual identity traits used to keep generated persona media consistent. Omitted optional modifiers are stored as none." } }, "additionalProperties": false, "description": "An unsaved complete persona profile used only to render a preview. It is captured in the generation snapshot and is not persisted by this request." }, "portrayedAge": { "$ref": "#/components/schemas/Int", "description": "a number between 15 and 75", "title": "between(15, 75)", "minimum": 15, "maximum": 75 }, "cameraView": { "type": "string", "enum": [ "front", "three_quarter", "profile", "back" ], "description": "The requested camera angle for the new persona image: front, three-quarter, profile, or back." }, "framing": { "type": "string", "enum": [ "headshot", "portrait", "half_body", "full_body" ], "description": "The requested composition for the new persona image, such as a headshot or full-body view." }, "lifeEventIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "maxItems": 100 }, "modelId": { "type": "string", "description": "Persona image requests use google/gemini-3.1-pro-image. Omit modelId or provide that value. New requests for another model are rejected before setup or generation; matching accepted requests retain their original replay behaviour.", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "seed": { "$ref": "#/components/schemas/Int" } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.renderPersonaView({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n personaId: process.env.OCTOSPARK_PERSONA_ID ?? \"personaId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.render_persona_view(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n personaId=os.environ.get(\"OCTOSPARK_PERSONA_ID\", \"personaId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas render-persona-view \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"personaId\":\"personaId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let persona_id = env::var(\"OCTOSPARK_PERSONA_ID\").unwrap_or_else(|_| \"personaId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/{}/render\", base_url.trim_end_matches('/'), team_id, persona_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final personaId = Platform.environment['OCTOSPARK_PERSONA_ID'] ?? 'personaId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/$personaId/render';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Render persona view", "x-displayName": "Render persona view" } }, "/v1/teams/{teamId}/personas/{personaId}/speech": { "post": { "tags": [ "Personas" ], "operationId": "personas.synthesizePersonaSpeech", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "personaId", "in": "path", "schema": { "type": "string", "description": "Persona id (UUID), returned by list or create persona." }, "required": true, "description": "Persona id (UUID), returned by list or create persona." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "assetId", "voiceId", "characters" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "voiceId": { "$ref": "#/components/schemas/UUID" }, "characters": { "$ref": "#/components/schemas/Int" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Generate and save an MP3 with the selected voice using the team ElevenLabs key. No Octospark AI credits are charged.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "a string at most 2500 character(s) long", "title": "maxLength(2500)", "minLength": 1, "maxLength": 2500 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.synthesizePersonaSpeech({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n personaId: process.env.OCTOSPARK_PERSONA_ID ?? \"personaId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.synthesize_persona_speech(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n personaId=os.environ.get(\"OCTOSPARK_PERSONA_ID\", \"personaId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas synthesize-persona-speech \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"personaId\":\"personaId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let persona_id = env::var(\"OCTOSPARK_PERSONA_ID\").unwrap_or_else(|_| \"personaId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/{}/speech\", base_url.trim_end_matches('/'), team_id, persona_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final personaId = Platform.environment['OCTOSPARK_PERSONA_ID'] ?? 'personaId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/$personaId/speech';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Synthesize persona speech", "x-displayName": "Synthesize persona speech" } }, "/v1/teams/{teamId}/personas/voice-connection": { "get": { "tags": [ "Personas" ], "operationId": "personas.getPersonaVoiceConnection", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "connected", "keyHint", "lastSyncedAt" ], "properties": { "connected": { "type": "boolean" }, "keyHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastSyncedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Inspect the team voice connection status and key hint without returning its credential. Requires sources permission.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.getPersonaVoiceConnection({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.get_persona_voice_connection(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas get-persona-voice-connection \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/voice-connection\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/voice-connection';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Persona voice connection", "x-displayName": "Persona voice connection" }, "put": { "tags": [ "Personas" ], "operationId": "personas.connectPersonaVoice", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "voiceCount" ], "properties": { "voiceCount": { "$ref": "#/components/schemas/Int" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Connect the team ElevenLabs credential through Octospark and synchronise available voices. Requires manage-integrations permission.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "apiKey" ], "properties": { "apiKey": { "type": "string", "description": "a string at most 300 character(s) long", "title": "maxLength(300)", "minLength": 10, "maxLength": 300 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.connectPersonaVoice({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.connect_persona_voice(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas connect-persona-voice \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/voice-connection\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.put(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/voice-connection';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.put(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Connect persona voice", "x-displayName": "Connect persona voice" }, "delete": { "tags": [ "Personas" ], "operationId": "personas.disconnectPersonaVoice", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Disconnect the team voice credential and clear its catalogue. Requires manage-integrations permission.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.disconnectPersonaVoice({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.disconnect_persona_voice(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas disconnect-persona-voice \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/voice-connection\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/voice-connection';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Disconnect persona voice", "x-displayName": "Disconnect persona voice" } }, "/v1/teams/{teamId}/personas/voices": { "get": { "tags": [ "Personas" ], "operationId": "personas.listPersonaVoices", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "providerVoiceId", "displayName", "description", "labels", "language", "providerCategory", "isAvailable", "isPersonaSelectable", "personaCatalogKey", "personaCatalogOrder", "previewStoragePath", "previewContentHash", "lastSyncedAt", "lastSyncErrorAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "providerVoiceId": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "displayName": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "description": { "anyOf": [ { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "labels": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "type": "string" } }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerCategory": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isAvailable": { "type": "boolean" }, "isPersonaSelectable": { "type": "boolean" }, "personaCatalogKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "personaCatalogOrder": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "previewStoragePath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "previewContentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastSyncedAt": { "type": "string" }, "lastSyncErrorAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List ElevenLabs voices available with the connected team key.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.listPersonaVoices({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.list_persona_voices(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas list-persona-voices \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/voices\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/voices';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List persona voices", "x-displayName": "List persona voices" }, "post": { "tags": [ "Personas" ], "operationId": "personas.addPersonaVoice", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "providerVoiceId", "displayName", "description", "labels", "language", "providerCategory", "isAvailable", "isPersonaSelectable", "personaCatalogKey", "personaCatalogOrder", "previewStoragePath", "previewContentHash", "lastSyncedAt", "lastSyncErrorAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "providerVoiceId": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "displayName": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "description": { "anyOf": [ { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "labels": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "type": "string" } }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerCategory": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isAvailable": { "type": "boolean" }, "isPersonaSelectable": { "type": "boolean" }, "personaCatalogKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "personaCatalogOrder": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "previewStoragePath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "previewContentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastSyncedAt": { "type": "string" }, "lastSyncErrorAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Register an accessible voice in the team catalogue using the connected credential. Requires manage-integrations permission.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "providerVoiceId" ], "properties": { "providerVoiceId": { "type": "string", "description": "a string at most 80 character(s) long", "title": "maxLength(80)", "minLength": 8, "maxLength": 80 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.addPersonaVoice({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.add_persona_voice(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas add-persona-voice \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/voices\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/voices';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Add persona voice", "x-displayName": "Add persona voice" } }, "/v1/teams/{teamId}/personas/voices/refresh": { "post": { "tags": [ "Personas" ], "operationId": "personas.refreshPersonaVoices", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "voiceCount" ], "properties": { "voiceCount": { "$ref": "#/components/schemas/Int" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Refresh the available voice catalogue using the connected team credential. Requires manage-integrations permission.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.personas.refreshPersonaVoices({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.personas.refresh_persona_voices(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark personas refresh-persona-voices \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/personas/voices/refresh\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/personas/voices/refresh';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.post(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Refresh persona voices", "x-displayName": "Refresh persona voices" } }, "/v1/teams/{teamId}/posts/{postId}/activity": { "get": { "tags": [ "Post notes" ], "operationId": "postNotes.listPostActivity", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "action", "actorName", "actorEmail", "createdAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "action": { "type": "string" }, "actorName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actorEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "The post's accountability trail, oldest first: submitted for review, withdrawn, workspace overrides, review links shared or revoked, and publication - each with who did it and when. Read from the existing audit trail, so it reflects what actually happened rather than a separate log that could drift.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.postNotes.listPostActivity({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.post_notes.list_post_activity(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark post-notes list-post-activity \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/activity\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/activity';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List post activity", "x-displayName": "List post activity" } }, "/v1/teams/{teamId}/posts/{postId}/assignees": { "put": { "tags": [ "Tasks" ], "operationId": "tasks.setPostAssignees", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "userId", "name", "email" ], "properties": { "userId": { "$ref": "#/components/schemas/UUID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Replace a post's full assignee set with the given team-member user ids (an empty array clears every assignment; non-members are silently ignored). Returns the post's resulting assignee set with display data.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "assigneeUserIds" ], "properties": { "assigneeUserIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Full replacement set of team-member user ids to assign to the post; an empty array clears every assignment. Non-members are silently ignored." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tasks.setPostAssignees({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tasks.set_post_assignees(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tasks set-post-assignees \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/assignees\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.put(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/assignees';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.put(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Set post assignees", "x-displayName": "Set post assignees" } }, "/v1/teams/{teamId}/posts/{postId}/notes": { "get": { "tags": [ "Post notes" ], "operationId": "postNotes.listPostNotes", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "mentionedUserIds", "id", "teamId", "postId", "body", "bodyDoc", "createdBy", "authorName", "authorEmail", "createdAt", "updatedAt" ], "properties": { "mentionedUserIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "postId": { "$ref": "#/components/schemas/UUID" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyDoc": { "anyOf": [ { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "createdBy": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "authorName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "authorEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List a post's internal working notes, oldest first, with author display data. Notes are internal to the workspace - they are never shown on a client review link. Unlike review comments, notes work on a plain draft and in workspaces that have approvals turned off.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.postNotes.listPostNotes({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.post_notes.list_post_notes(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark post-notes list-post-notes \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/notes\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/notes';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List post notes", "x-displayName": "List post notes" }, "post": { "tags": [ "Post notes" ], "operationId": "postNotes.createPostNote", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "mentionedUserIds", "id", "teamId", "postId", "body", "bodyDoc", "createdBy", "authorName", "authorEmail", "createdAt", "updatedAt" ], "properties": { "mentionedUserIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "postId": { "$ref": "#/components/schemas/UUID" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyDoc": { "anyOf": [ { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "createdBy": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "authorName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "authorEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Add an internal working note to a post. Send the plain-text body, the rich bodyDoc block document, or both - at least one must carry content. Never spends credits.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "mentionedUserIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "User ids mentioned in the body, in the order they were inserted. Up to 20; ids outside the owning team are ignored.", "title": "maxItems(20)", "maxItems": 20 }, "body": { "type": "string", "description": "Plain-text mirror of the note, used for search and previews. Up to 10,000 characters. Keep it in sync with bodyDoc.", "title": "maxLength(10000)", "maxLength": 10000 }, "bodyDoc": { "anyOf": [ { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ], "description": "Rich (block-based) note document, stored verbatim for the notes editor. Send null to clear it; keep the plain-text body field in sync." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.postNotes.createPostNote({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.post_notes.create_post_note(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark post-notes create-post-note \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/notes\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/notes';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create post note", "x-displayName": "Create post note" } }, "/v1/teams/{teamId}/posts/{postId}/notes/{noteId}": { "get": { "tags": [ "Post notes" ], "operationId": "postNotes.getPostNote", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, { "name": "noteId", "in": "path", "schema": { "type": "string", "description": "Post note id (UUID), as returned by the list/create post-note endpoints." }, "required": true, "description": "Post note id (UUID), as returned by the list/create post-note endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "mentionedUserIds", "id", "teamId", "postId", "body", "bodyDoc", "createdBy", "authorName", "authorEmail", "createdAt", "updatedAt" ], "properties": { "mentionedUserIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "postId": { "$ref": "#/components/schemas/UUID" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyDoc": { "anyOf": [ { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "createdBy": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "authorName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "authorEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Fetch one internal note on a post, with its rich note document and author display data.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.postNotes.getPostNote({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n noteId: process.env.OCTOSPARK_NOTE_ID ?? \"noteId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.post_notes.get_post_note(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\"),\n noteId=os.environ.get(\"OCTOSPARK_NOTE_ID\", \"noteId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark post-notes get-post-note \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\",\"noteId\":\"noteId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let note_id = env::var(\"OCTOSPARK_NOTE_ID\").unwrap_or_else(|_| \"noteId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/notes/{}\", base_url.trim_end_matches('/'), team_id, post_id, note_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final noteId = Platform.environment['OCTOSPARK_NOTE_ID'] ?? 'noteId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/notes/$noteId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Post note", "x-displayName": "Post note" }, "patch": { "tags": [ "Post notes" ], "operationId": "postNotes.updatePostNote", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, { "name": "noteId", "in": "path", "schema": { "type": "string", "description": "Post note id (UUID), as returned by the list/create post-note endpoints." }, "required": true, "description": "Post note id (UUID), as returned by the list/create post-note endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "mentionedUserIds", "id", "teamId", "postId", "body", "bodyDoc", "createdBy", "authorName", "authorEmail", "createdAt", "updatedAt" ], "properties": { "mentionedUserIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "postId": { "$ref": "#/components/schemas/UUID" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyDoc": { "anyOf": [ { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "createdBy": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "authorName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "authorEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Edit an internal note on a post. Omitted fields are left unchanged; null clears a field. Any teammate holding the notes permission can edit any note - notes are shared working memory, not personal property.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "body": { "anyOf": [ { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "maxLength": 10000 }, { "type": "null" } ], "description": "Plain-text mirror of the note. Send null to clear it; omit to leave unchanged." }, "bodyDoc": { "anyOf": [ { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ], "description": "Rich (block-based) note document, stored verbatim for the notes editor. Send null to clear it; keep the plain-text body field in sync." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.postNotes.updatePostNote({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n noteId: process.env.OCTOSPARK_NOTE_ID ?? \"noteId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.post_notes.update_post_note(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\"),\n noteId=os.environ.get(\"OCTOSPARK_NOTE_ID\", \"noteId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark post-notes update-post-note \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\",\"noteId\":\"noteId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let note_id = env::var(\"OCTOSPARK_NOTE_ID\").unwrap_or_else(|_| \"noteId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/notes/{}\", base_url.trim_end_matches('/'), team_id, post_id, note_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final noteId = Platform.environment['OCTOSPARK_NOTE_ID'] ?? 'noteId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/notes/$noteId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Update post note", "x-displayName": "Update post note" }, "delete": { "tags": [ "Post notes" ], "operationId": "postNotes.deletePostNote", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, { "name": "noteId", "in": "path", "schema": { "type": "string", "description": "Post note id (UUID), as returned by the list/create post-note endpoints." }, "required": true, "description": "Post note id (UUID), as returned by the list/create post-note endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Delete an internal note on a post. This cannot be undone. Review decisions and client comments are unaffected - those are the approval audit trail and are never deletable this way.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.postNotes.deletePostNote({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n noteId: process.env.OCTOSPARK_NOTE_ID ?? \"noteId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.post_notes.delete_post_note(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\"),\n noteId=os.environ.get(\"OCTOSPARK_NOTE_ID\", \"noteId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark post-notes delete-post-note \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\",\"noteId\":\"noteId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let note_id = env::var(\"OCTOSPARK_NOTE_ID\").unwrap_or_else(|_| \"noteId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/notes/{}\", base_url.trim_end_matches('/'), team_id, post_id, note_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final noteId = Platform.environment['OCTOSPARK_NOTE_ID'] ?? 'noteId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/notes/$noteId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete post note", "x-displayName": "Delete post note" } }, "/v1/teams/{teamId}/posts/{postId}/tags": { "post": { "tags": [ "Tags" ], "operationId": "tags.addPostTag", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "colour" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Assign one existing registry tag to a post (no-op if already assigned). Returns the post's resulting tag set. Create the tag first via createTag if it does not exist yet.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "tagId" ], "properties": { "tagId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tags.addPostTag({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tags.add_post_tag(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tags add-post-tag \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/tags\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/tags';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Add post tag", "x-displayName": "Add post tag" }, "put": { "tags": [ "Tags" ], "operationId": "tags.setPostTags", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "colour" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Replace a post's full tag assignment with the given set of tag ids (an empty array clears all tags). Returns the post's resulting tag set. Use addPostTag/removePostTag for single-tag changes.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "tagIds" ], "properties": { "tagIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Full replacement set of registry tag ids for the post; an empty array clears every tag assignment." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tags.setPostTags({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tags.set_post_tags(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tags set-post-tags \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/tags\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.put(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/tags';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.put(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Set post tags", "x-displayName": "Set post tags" } }, "/v1/teams/{teamId}/posts/{postId}/tags/{tagId}": { "delete": { "tags": [ "Tags" ], "operationId": "tags.removePostTag", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, { "name": "tagId", "in": "path", "schema": { "type": "string", "description": "Tag id (UUID) from the team tag registry, as returned by the list tags endpoint." }, "required": true, "description": "Tag id (UUID) from the team tag registry, as returned by the list tags endpoint." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "colour" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Remove one tag assignment from a post, leaving the tag itself in the registry. Returns the post's resulting tag set after the removal.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tags.removePostTag({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n tagId: process.env.OCTOSPARK_TAG_ID ?? \"tagId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tags.remove_post_tag(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\"),\n tagId=os.environ.get(\"OCTOSPARK_TAG_ID\", \"tagId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tags remove-post-tag \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\",\"tagId\":\"tagId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let tag_id = env::var(\"OCTOSPARK_TAG_ID\").unwrap_or_else(|_| \"tagId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/tags/{}\", base_url.trim_end_matches('/'), team_id, post_id, tag_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final tagId = Platform.environment['OCTOSPARK_TAG_ID'] ?? 'tagId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/tags/$tagId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete post tag", "x-displayName": "Delete post tag" } }, "/v1/teams/{teamId}/posts/{postId}/workflow-status": { "put": { "tags": [ "Workflow statuses" ], "operationId": "workflowStatuses.setPostWorkflowStatus", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "postId", "in": "path", "schema": { "type": "string", "description": "Post id (UUID), as returned by the create post and list posts endpoints." }, "required": true, "description": "Post id (UUID), as returned by the create post and list posts endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "name", "colour", "position", "appliesTo", "category", "autoPostEligible", "isTerminal", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" }, "position": { "type": "number" }, "appliesTo": { "type": "string", "enum": [ "content", "task" ] }, "category": { "type": "string", "enum": [ "not_started", "active", "in_review", "completed", "closed" ] }, "autoPostEligible": { "type": "boolean" }, "isTerminal": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Move a post to a content workflow status owned by the same workspace. Task statuses and statuses from another workspace are rejected.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "workflowStatusId" ], "properties": { "workflowStatusId": { "type": "string", "description": "Content workflow status id to assign to the post.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.workflowStatuses.setPostWorkflowStatus({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n postId: process.env.OCTOSPARK_POST_ID ?? \"postId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.workflow_statuses.set_post_workflow_status(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n postId=os.environ.get(\"OCTOSPARK_POST_ID\", \"postId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark workflow-statuses set-post-workflow-status \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"postId\":\"postId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let post_id = env::var(\"OCTOSPARK_POST_ID\").unwrap_or_else(|_| \"postId\".to_string());\n let url = format!(\"{}/v1/teams/{}/posts/{}/workflow-status\", base_url.trim_end_matches('/'), team_id, post_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.put(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final postId = Platform.environment['OCTOSPARK_POST_ID'] ?? 'postId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/posts/$postId/workflow-status';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.put(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Set post workflow status", "x-displayName": "Set post workflow status" } }, "/v1/teams/{teamId}/shortlinks": { "get": { "tags": [ "Shortlinks" ], "operationId": "shortlinks.listShortlinks", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "slug", "targetUrl", "placement", "displayMode", "platform", "status", "clickCount", "createdAt", "publishedAt", "expiresAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "slug": { "type": "string" }, "targetUrl": { "type": "string" }, "placement": { "type": "string", "enum": [ "caption", "media_cta", "description", "bio", "carousel_slide" ] }, "displayMode": { "type": "string", "enum": [ "clickable", "in_media_url", "in_media_qr" ] }, "platform": { "anyOf": [ { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads", "pinterest" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, threads, or pinterest.", "examples": [ "x" ] }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "expired", "retired" ] }, "clickCount": { "type": "number" }, "createdAt": { "type": "string" }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the team's tracked shortlinks with their total click counts. Shortlinks are minted automatically when link tracking is enabled on a published post; use getClicksByDimension for a per-link click breakdown.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.shortlinks.listShortlinks({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.shortlinks.list_shortlinks(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark shortlinks list-shortlinks \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/shortlinks\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/shortlinks';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List shortlinks", "x-displayName": "List shortlinks" } }, "/v1/teams/{teamId}/shortlinks/{id}/clicks": { "get": { "tags": [ "Shortlinks" ], "operationId": "shortlinks.getClicksByDimension", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "id", "in": "path", "schema": { "type": "string", "description": "Shortlink id (UUID), as returned by the list shortlinks endpoint." }, "required": true, "description": "Shortlink id (UUID), as returned by the list shortlinks endpoint." }, { "name": "groupBy", "in": "query", "schema": { "type": "string", "enum": [ "platform", "placement", "display_mode", "content_type", "target_domain", "referrer", "device", "country" ], "description": "Dimension to bucket the shortlink's clicks by, e.g. referrer, country, or device." }, "required": true, "description": "Dimension to bucket the shortlink's clicks by, e.g. referrer, country, or device." }, { "name": "from", "in": "query", "schema": { "type": "string", "description": "Start of the click window, ISO 8601 timestamp (inclusive); omit for all time.", "examples": [ "2026-06-01T00:00:00Z" ] }, "required": false, "description": "Start of the click window, ISO 8601 timestamp (inclusive); omit for all time." }, { "name": "to", "in": "query", "schema": { "type": "string", "description": "End of the click window, ISO 8601 timestamp (inclusive); omit for all time.", "examples": [ "2026-06-30T23:59:59Z" ] }, "required": false, "description": "End of the click window, ISO 8601 timestamp (inclusive); omit for all time." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "dimension", "buckets" ], "properties": { "dimension": { "type": "string", "enum": [ "platform", "placement", "display_mode", "content_type", "target_domain", "referrer", "device", "country" ] }, "buckets": { "type": "array", "items": { "type": "object", "required": [ "key", "humanClicks" ], "properties": { "key": { "type": "string" }, "humanClicks": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Break down one shortlink's recorded clicks by a grouping dimension (such as referrer, country, or device) within an optional time window. Free: reads stored click events only.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.shortlinks.getClicksByDimension({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n id: process.env.OCTOSPARK_ID ?? \"id\",\n query: {\n \"groupBy\": process.env.OCTOSPARK_GROUP_BY ?? \"groupBy\",\n },\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.shortlinks.get_clicks_by_dimension(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n id=os.environ.get(\"OCTOSPARK_ID\", \"id\"),\n query={\n \"groupBy\": os.environ.get(\"OCTOSPARK_GROUP_BY\", \"groupBy\"),\n }\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark shortlinks get-clicks-by-dimension \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"id\":\"id\"},\"query\":{\"groupBy\":\"groupBy\",\"from\":\"from\",\"to\":\"to\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let id = env::var(\"OCTOSPARK_ID\").unwrap_or_else(|_| \"id\".to_string());\n let group_by = env::var(\"OCTOSPARK_GROUP_BY\").unwrap_or_else(|_| \"groupBy\".to_string());\n let url = format!(\"{}/v1/teams/{}/shortlinks/{}/clicks\", base_url.trim_end_matches('/'), team_id, id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let query = [(\"groupBy\", group_by.as_str())];\n request = request.query(&query);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final id = Platform.environment['OCTOSPARK_ID'] ?? 'id';\n final groupBy = Platform.environment['OCTOSPARK_GROUP_BY'] ?? 'groupBy';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/shortlinks/$id/clicks';\n final uri = Uri.parse(url).replace(queryParameters: {\n 'groupBy': groupBy,\n });\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Clicks by dimension", "x-displayName": "Clicks by dimension" } }, "/v1/teams/{teamId}/sources": { "get": { "tags": [ "Sources" ], "operationId": "sources.listSources", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, "required": false, "description": "Opaque pagination cursor from the previous page response (nextCursor/prevCursor); omit to start at the first page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "Page size as a positive integer string; defaults to 25, capped at 100.", "default": "25", "examples": [ "25", "100" ] }, "required": false, "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt.", "examples": [ "createdAt" ] }, "required": false, "description": "Field to sort by; each endpoint accepts its own allowlist and defaults to createdAt." }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction: asc or desc; defaults to desc.", "default": "desc" }, "required": false, "description": "Sort direction: asc or desc; defaults to desc." }, { "name": "filter[status]", "in": "query", "schema": { "type": "string", "enum": [ "pending", "extracting", "ready", "failed", "skipped_insufficient_credits" ], "description": "Restrict results to sources in this ingestion status: pending, extracting, ready, failed, or skipped_insufficient_credits.", "examples": [ "ready" ] }, "required": false, "description": "Restrict results to sources in this ingestion status: pending, extracting, ready, failed, or skipped_insufficient_credits." }, { "name": "filter[type]", "in": "query", "schema": { "type": "string", "enum": [ "text", "article", "youtube", "tiktok", "audio", "pdf", "skill" ], "description": "Restrict results to one source type (text, article, youtube, tiktok, audio, pdf, or skill).", "examples": [ "article" ] }, "required": false, "description": "Restrict results to one source type (text, article, youtube, tiktok, audio, pdf, or skill)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "sourceType", "title", "status", "statusError", "saved", "usedCount", "lastUsedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "text", "article", "youtube", "tiktok", "audio", "pdf", "skill" ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "extracting", "ready", "failed", "skipped_insufficient_credits" ] }, "statusError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "saved": { "type": "boolean" }, "usedCount": { "type": "number", "description": "How many posts have been created from this source (derived from post-from-source provenance, never a stored counter). List with sortBy=usedCount&sortOrder=asc to claim the least-used source first and keep content ideas fresh.", "examples": [ 0 ] }, "lastUsedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When a post was last created from this source (ISO timestamp); null when the source has never been used." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the team's content sources with cursor pagination, including each source's ingestion status and usage (usedCount/lastUsedAt, derived from posts created with sourceIds). Filter by status or source type to find pending, failed, or completed extractions. Sort with sortBy=usedCount&sortOrder=asc to get the least-used sources first - the way to honour briefs like \"use the least claimed source to keep content ideas fresh\".", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.sources.listSources({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.sources.list_sources(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark sources list-sources \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/sources\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/sources';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List sources", "x-displayName": "List sources" }, "post": { "tags": [ "Sources" ], "operationId": "sources.createSource", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "sourceType", "title", "status", "statusError", "saved", "usedCount", "lastUsedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "text", "article", "youtube", "tiktok", "audio", "pdf", "skill" ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "extracting", "ready", "failed", "skipped_insufficient_credits" ] }, "statusError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "saved": { "type": "boolean" }, "usedCount": { "type": "number", "description": "How many posts have been created from this source (derived from post-from-source provenance, never a stored counter). List with sortBy=usedCount&sortOrder=asc to claim the least-used source first and keep content ideas fresh.", "examples": [ 0 ] }, "lastUsedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When a post was last created from this source (ISO timestamp); null when the source has never been used." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Register a content source (url, text, or uploaded file) for ingestion. Returns 202: the source row commits immediately and extraction runs asynchronously in the worker; poll getSource or listSources for the extraction status. Paid extraction (e.g. TikTok fetches, embeddings) debits credits in the worker pipeline, not at this endpoint.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "sourceType" ], "properties": { "sourceType": { "type": "string", "enum": [ "text", "article", "youtube", "tiktok", "audio", "pdf", "skill" ], "description": "Kind of source to ingest: text, article, youtube, tiktok, audio, pdf, or skill. Determines which of url, text, or storagePath is required.", "examples": [ "article" ] }, "url": { "type": "string", "description": "Public URL to extract from; required for article, youtube, and tiktok sources.", "examples": [ "https://example.com/blog/launch-post" ] }, "text": { "type": "string", "description": "Raw text content to ingest directly; required for text sources." }, "storagePath": { "type": "string", "description": "Storage path returned by createSourceUploadUrl after uploading the file; required for audio and pdf sources." }, "title": { "type": "string", "description": "Display title for the source; derived from the content when omitted.", "examples": [ "Q3 launch blog post" ] }, "customInstructions": { "type": "string", "description": "Optional guidance for the extraction step, e.g. what to focus on or ignore.", "examples": [ "Focus on the pricing changes; skip the changelog." ] }, "saved": { "type": "boolean", "description": "Whether to keep the source permanently (true) or leave it as a retention candidate (default false)." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.sources.createSource({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.sources.create_source(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark sources create-source \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/sources\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/sources';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create source", "x-displayName": "Create source" } }, "/v1/teams/{teamId}/sources/{sourceId}": { "get": { "tags": [ "Sources" ], "operationId": "sources.getSource", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "sourceId", "in": "path", "schema": { "type": "string", "description": "Content source id (UUID), as returned by the create source and list sources endpoints." }, "required": true, "description": "Content source id (UUID), as returned by the create source and list sources endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "source", "extraction", "toolCallId", "creditsUsedDecimillicents" ], "properties": { "source": { "type": "object", "required": [ "id", "teamId", "sourceType", "title", "status", "statusError", "saved", "usedCount", "lastUsedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "text", "article", "youtube", "tiktok", "audio", "pdf", "skill" ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "extracting", "ready", "failed", "skipped_insufficient_credits" ] }, "statusError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "saved": { "type": "boolean" }, "usedCount": { "type": "number", "description": "How many posts have been created from this source (derived from post-from-source provenance, never a stored counter). List with sortBy=usedCount&sortOrder=asc to claim the least-used source first and keep content ideas fresh.", "examples": [ 0 ] }, "lastUsedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When a post was last created from this source (ISO timestamp); null when the source has never been used." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, "extraction": { "anyOf": [ { "type": "object", "required": [ "extractedText", "summary", "imageUrls", "sourceMetadata" ], "properties": { "extractedText": { "type": "string" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imageUrls": { "type": "array", "items": { "type": "string" } }, "sourceMetadata": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } } }, "additionalProperties": false }, { "type": "null" } ] }, "toolCallId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "creditsUsedDecimillicents": { "type": "number" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Fetch one content source with its extraction detail (extracted text, summary, ingestion status, and failure reason if extraction failed). Use after createSource to poll for extraction completion.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.sources.getSource({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n sourceId: process.env.OCTOSPARK_SOURCE_ID ?? \"sourceId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.sources.get_source(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n sourceId=os.environ.get(\"OCTOSPARK_SOURCE_ID\", \"sourceId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark sources get-source \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"sourceId\":\"sourceId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let source_id = env::var(\"OCTOSPARK_SOURCE_ID\").unwrap_or_else(|_| \"sourceId\".to_string());\n let url = format!(\"{}/v1/teams/{}/sources/{}\", base_url.trim_end_matches('/'), team_id, source_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final sourceId = Platform.environment['OCTOSPARK_SOURCE_ID'] ?? 'sourceId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/sources/$sourceId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Get source", "x-displayName": "Get source" }, "delete": { "tags": [ "Sources" ], "operationId": "sources.deleteSource", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "sourceId", "in": "path", "schema": { "type": "string", "description": "Content source id (UUID), as returned by the create source and list sources endpoints." }, "required": true, "description": "Content source id (UUID), as returned by the create source and list sources endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Delete a content source and its extraction from the team. Brands referencing the source simply stop including it; already-generated content is unaffected. This does not refund any credits spent on its ingestion.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.sources.deleteSource({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n sourceId: process.env.OCTOSPARK_SOURCE_ID ?? \"sourceId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.sources.delete_source(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n sourceId=os.environ.get(\"OCTOSPARK_SOURCE_ID\", \"sourceId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark sources delete-source \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"sourceId\":\"sourceId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let source_id = env::var(\"OCTOSPARK_SOURCE_ID\").unwrap_or_else(|_| \"sourceId\".to_string());\n let url = format!(\"{}/v1/teams/{}/sources/{}\", base_url.trim_end_matches('/'), team_id, source_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final sourceId = Platform.environment['OCTOSPARK_SOURCE_ID'] ?? 'sourceId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/sources/$sourceId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete source", "x-displayName": "Delete source" } }, "/v1/teams/{teamId}/sources/{sourceId}/extraction": { "patch": { "tags": [ "Sources" ], "operationId": "sources.editExtraction", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "sourceId", "in": "path", "schema": { "type": "string", "description": "Content source id (UUID), as returned by the create source and list sources endpoints." }, "required": true, "description": "Content source id (UUID), as returned by the create source and list sources endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "extractedText", "summary", "imageUrls", "sourceMetadata" ], "properties": { "extractedText": { "type": "string" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imageUrls": { "type": "array", "items": { "type": "string" } }, "sourceMetadata": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Edit the extracted text and/or summary of a source's completed extraction, e.g. to correct or trim what the ingestion pipeline produced. Editing already-extracted text is free and returns the updated extraction.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "extractedText": { "type": "string", "description": "Replacement extracted text for the source; omit to leave it unchanged. The route rejects a patch with neither field." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Replacement summary; null clears the stored summary, omit to leave it unchanged." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.sources.editExtraction({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n sourceId: process.env.OCTOSPARK_SOURCE_ID ?? \"sourceId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.sources.edit_extraction(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n sourceId=os.environ.get(\"OCTOSPARK_SOURCE_ID\", \"sourceId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark sources edit-extraction \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"sourceId\":\"sourceId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let source_id = env::var(\"OCTOSPARK_SOURCE_ID\").unwrap_or_else(|_| \"sourceId\".to_string());\n let url = format!(\"{}/v1/teams/{}/sources/{}/extraction\", base_url.trim_end_matches('/'), team_id, source_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final sourceId = Platform.environment['OCTOSPARK_SOURCE_ID'] ?? 'sourceId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/sources/$sourceId/extraction';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Edit extraction", "x-displayName": "Edit extraction" } }, "/v1/teams/{teamId}/sources/{sourceId}/reingest": { "post": { "tags": [ "Sources" ], "operationId": "sources.reingestSource", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "sourceId", "in": "path", "schema": { "type": "string", "description": "Content source id (UUID), as returned by the create source and list sources endpoints." }, "required": true, "description": "Content source id (UUID), as returned by the create source and list sources endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "sourceType", "title", "status", "statusError", "saved", "usedCount", "lastUsedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "text", "article", "youtube", "tiktok", "audio", "pdf", "skill" ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "extracting", "ready", "failed", "skipped_insufficient_credits" ] }, "statusError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "saved": { "type": "boolean" }, "usedCount": { "type": "number", "description": "How many posts have been created from this source (derived from post-from-source provenance, never a stored counter). List with sortBy=usedCount&sortOrder=asc to claim the least-used source first and keep content ideas fresh.", "examples": [ 0 ] }, "lastUsedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When a post was last created from this source (ISO timestamp); null when the source has never been used." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Re-run extraction for an existing source (e.g. after the underlying URL content changed or a previous extraction failed). Returns 202 and processes asynchronously in the worker; paid extraction debits credits there, exactly like createSource.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.sources.reingestSource({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n sourceId: process.env.OCTOSPARK_SOURCE_ID ?? \"sourceId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.sources.reingest_source(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n sourceId=os.environ.get(\"OCTOSPARK_SOURCE_ID\", \"sourceId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark sources reingest-source \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"sourceId\":\"sourceId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let source_id = env::var(\"OCTOSPARK_SOURCE_ID\").unwrap_or_else(|_| \"sourceId\".to_string());\n let url = format!(\"{}/v1/teams/{}/sources/{}/reingest\", base_url.trim_end_matches('/'), team_id, source_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final sourceId = Platform.environment['OCTOSPARK_SOURCE_ID'] ?? 'sourceId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/sources/$sourceId/reingest';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.post(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Reingest source", "x-displayName": "Reingest source" } }, "/v1/teams/{teamId}/sources/upload-url": { "post": { "tags": [ "Sources" ], "operationId": "sources.createSourceUploadUrl", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "uploadUrl", "storagePath" ], "properties": { "uploadUrl": { "type": "string" }, "storagePath": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Presign an upload URL for a file-based content source (e.g. a PDF or transcript). Upload the file bytes to the returned URL, then call createSource with the returned storagePath to start ingestion. Never spends credits.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "contentType", "fileName", "fileSize" ], "properties": { "contentType": { "type": "string", "description": "MIME type of the file to upload; allowlisted per source kind (audio or pdf).", "examples": [ "application/pdf" ] }, "fileName": { "type": "string", "description": "Original filename including extension, used to derive the storage path.", "examples": [ "episode-42.mp3" ] }, "fileSize": { "type": "number", "description": "File size in bytes; capped at issuance (100 MB for audio, 500 MB for pdf).", "examples": [ 1048576 ] } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.sources.createSourceUploadUrl({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.sources.create_source_upload_url(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark sources create-source-upload-url \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/sources/upload-url\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/sources/upload-url';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create source upload URL", "x-displayName": "Create source upload URL" } }, "/v1/teams/{teamId}/tags": { "get": { "tags": [ "Tags" ], "operationId": "tags.listTags", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "name", "colour", "createdBy", "createdAt", "updatedAt", "usageCount" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" }, "createdBy": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "usageCount": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the team's tag registry: user/agent-defined labels (name + colour) that can be assigned to posts for filtering and analytics grouping. Distinct from AI-derived asset tags, which are read-only enrichment output.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tags.listTags({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tags.list_tags(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tags list-tags \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/tags\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/tags';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List tags", "x-displayName": "List tags" }, "post": { "tags": [ "Tags" ], "operationId": "tags.createTag", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "name", "colour", "createdBy", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" }, "createdBy": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create a tag in the team registry with a name and colour. Tag names are unique per team; assign the returned tag to posts via the post tag endpoints. Never spends credits.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "colour" ], "properties": { "name": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "colour": { "type": "string", "description": "a string at most 32 character(s) long", "title": "maxLength(32)", "minLength": 1, "maxLength": 32 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tags.createTag({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tags.create_tag(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tags create-tag \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/tags\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/tags';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create tag", "x-displayName": "Create tag" } }, "/v1/teams/{teamId}/tags/{tagId}": { "patch": { "tags": [ "Tags" ], "operationId": "tags.updateTag", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "tagId", "in": "path", "schema": { "type": "string", "description": "Tag id (UUID) from the team tag registry, as returned by the list tags endpoint." }, "required": true, "description": "Tag id (UUID) from the team tag registry, as returned by the list tags endpoint." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "name", "colour", "createdBy", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" }, "createdBy": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Rename a tag or change its colour. The change applies everywhere the tag is already assigned; post assignments are untouched.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "colour": { "type": "string", "description": "a string at most 32 character(s) long", "title": "maxLength(32)", "minLength": 1, "maxLength": 32 } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tags.updateTag({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n tagId: process.env.OCTOSPARK_TAG_ID ?? \"tagId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tags.update_tag(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n tagId=os.environ.get(\"OCTOSPARK_TAG_ID\", \"tagId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tags update-tag \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"tagId\":\"tagId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let tag_id = env::var(\"OCTOSPARK_TAG_ID\").unwrap_or_else(|_| \"tagId\".to_string());\n let url = format!(\"{}/v1/teams/{}/tags/{}\", base_url.trim_end_matches('/'), team_id, tag_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final tagId = Platform.environment['OCTOSPARK_TAG_ID'] ?? 'tagId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/tags/$tagId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Update tag", "x-displayName": "Update tag" }, "delete": { "tags": [ "Tags" ], "operationId": "tags.deleteTag", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "tagId", "in": "path", "schema": { "type": "string", "description": "Tag id (UUID) from the team tag registry, as returned by the list tags endpoint." }, "required": true, "description": "Tag id (UUID) from the team tag registry, as returned by the list tags endpoint." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Delete a tag from the team registry, removing it from every post it was assigned to. The posts themselves are unaffected. This cannot be undone.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tags.deleteTag({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n tagId: process.env.OCTOSPARK_TAG_ID ?? \"tagId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tags.delete_tag(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n tagId=os.environ.get(\"OCTOSPARK_TAG_ID\", \"tagId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tags delete-tag \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"tagId\":\"tagId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let tag_id = env::var(\"OCTOSPARK_TAG_ID\").unwrap_or_else(|_| \"tagId\".to_string());\n let url = format!(\"{}/v1/teams/{}/tags/{}\", base_url.trim_end_matches('/'), team_id, tag_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final tagId = Platform.environment['OCTOSPARK_TAG_ID'] ?? 'tagId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/tags/$tagId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete tag", "x-displayName": "Delete tag" } }, "/v1/teams/{teamId}/tasks": { "get": { "tags": [ "Tasks" ], "operationId": "tasks.listTasks", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor from a previous response (nextCursor/prevCursor). Omit for the first page." }, "required": false, "description": "Opaque pagination cursor from a previous response (nextCursor/prevCursor). Omit for the first page." }, { "name": "limit", "in": "query", "schema": { "type": "string", "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, "required": false, "description": "Page size as a positive integer string; defaults to 25, capped at 100." }, { "name": "q", "in": "query", "schema": { "type": "string", "description": "Free-text search over task titles and descriptions (case-insensitive substring match). Omit or send an empty string for no text filter.", "title": "maxLength(200)", "maxLength": 200 }, "required": false, "description": "Free-text search over task titles and descriptions (case-insensitive substring match). Omit or send an empty string for no text filter." }, { "name": "scheduled", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Filter by due-date presence: 'true' returns only tasks WITH a due date, 'false' only tasks WITHOUT one. Omit for both. 'false' is the only way to select tasks with no due date, and combining it with dueBefore/dueAfter is rejected as contradictory." }, "required": false, "description": "Filter by due-date presence: 'true' returns only tasks WITH a due date, 'false' only tasks WITHOUT one. Omit for both. 'false' is the only way to select tasks with no due date, and combining it with dueBefore/dueAfter is rejected as contradictory." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "todo", "in_progress", "done" ], "description": "Legacy compatibility filter. Prefer workflowStatusId for dynamic board columns." }, "required": false, "description": "Legacy compatibility filter. Prefer workflowStatusId for dynamic board columns." }, { "name": "workflowStatusId", "in": "query", "schema": { "type": "string", "description": "Only return tasks assigned to this workspace task workflow status.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": false, "description": "Only return tasks assigned to this workspace task workflow status." }, { "name": "assigneeUserId", "in": "query", "schema": { "type": "string", "description": "Only return tasks assigned to this team member (user id, as returned by the list team members endpoint).", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": false, "description": "Only return tasks assigned to this team member (user id, as returned by the list team members endpoint)." }, { "name": "contentItemId", "in": "query", "schema": { "type": "string", "description": "Only return tasks attached to this post (post id, as returned by the list posts endpoint).", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "required": false, "description": "Only return tasks attached to this post (post id, as returned by the list posts endpoint)." }, { "name": "dueBefore", "in": "query", "schema": { "type": "string", "description": "ISO-8601 inclusive upper bound on the due date. Tasks without a due date are excluded when either due bound is set." }, "required": false, "description": "ISO-8601 inclusive upper bound on the due date. Tasks without a due date are excluded when either due bound is set." }, { "name": "dueAfter", "in": "query", "schema": { "type": "string", "description": "ISO-8601 inclusive lower bound on the due date. Tasks without a due date are excluded when either due bound is set." }, "required": false, "description": "ISO-8601 inclusive lower bound on the due date. Tasks without a due date are excluded when either due bound is set." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "title", "description", "descriptionDoc", "workflowStatusId", "status", "dueAt", "contentItemId", "contentItemTitle", "assignees", "tags", "createdBy", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "descriptionDoc": { "anyOf": [ { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "workflowStatusId": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string", "enum": [ "todo", "in_progress", "done" ] }, "dueAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentItemId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "contentItemTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assignees": { "type": "array", "items": { "type": "object", "required": [ "userId", "name", "email" ], "properties": { "userId": { "$ref": "#/components/schemas/UUID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "colour" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" } }, "additionalProperties": false } }, "createdBy": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the team's tasks (standalone or attached to a post), newest activity first, with assignees, registry tags, the authoritative workflow status id, and the attached post's title. Filter by workflow status, legacy status projection, assignee, attached post, or due-date bounds. Paginate with cursor/limit.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tasks.listTasks({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tasks.list_tasks(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tasks list-tasks \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/tasks\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/tasks';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List tasks", "x-displayName": "List tasks" }, "post": { "tags": [ "Tasks" ], "operationId": "tasks.createTask", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "title", "description", "descriptionDoc", "workflowStatusId", "status", "dueAt", "contentItemId", "contentItemTitle", "assignees", "tags", "createdBy", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "descriptionDoc": { "anyOf": [ { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "workflowStatusId": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string", "enum": [ "todo", "in_progress", "done" ] }, "dueAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentItemId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "contentItemTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assignees": { "type": "array", "items": { "type": "object", "required": [ "userId", "name", "email" ], "properties": { "userId": { "$ref": "#/components/schemas/UUID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "colour" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" } }, "additionalProperties": false } }, "createdBy": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create a task: title plus optional description, workspace task workflow status (defaults to the entry column), ISO-8601 due date, attached post (contentItemId), assignees, and registry tags. Assignees must be team members and tags must belong to the team - foreign ids are silently ignored. Never spends credits.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "Short imperative title for the task, 1-500 characters.", "title": "maxLength(500)", "minLength": 1, "maxLength": 500 }, "description": { "type": "string", "description": "Plain-text description used for search, card excerpts, and previews. Up to 10,000 characters.", "title": "maxLength(10000)", "maxLength": 10000 }, "descriptionDoc": { "anyOf": [ { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ], "description": "Rich (block-based) description document, stored verbatim for the task editor. Send null to clear it. Keep the plain-text description field in sync for search and previews." }, "workflowStatusId": { "type": "string", "description": "Workspace-owned task workflow status id. Omit on create to use the first not_started task status.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "status": { "type": "string", "enum": [ "todo", "in_progress", "done" ], "description": "Legacy task-state projection retained for checklist and summary compatibility. The workspace workflow status is authoritative." }, "dueAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 instant the task is due. Send null to clear the due date; tasks with a due date also appear on the calendar." }, "contentItemId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ], "description": "Id of the post this task is attached to (its checklist), as returned by the list posts endpoint. Send null to detach; attached tasks are removed with their post." }, "assigneeUserIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Full replacement set of team-member user ids assigned to the task; an empty array clears every assignment. Non-members are silently ignored." }, "tagIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Full replacement set of registry tag ids on the task (same registry as post tags); an empty array clears them. Tags from other teams are silently ignored." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tasks.createTask({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tasks.create_task(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tasks create-task \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/tasks\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/tasks';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create task", "x-displayName": "Create task" } }, "/v1/teams/{teamId}/tasks/{taskId}": { "get": { "tags": [ "Tasks" ], "operationId": "tasks.getTask", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "taskId", "in": "path", "schema": { "type": "string", "description": "Task id (UUID), as returned by the list/create task endpoints." }, "required": true, "description": "Task id (UUID), as returned by the list/create task endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "title", "description", "descriptionDoc", "workflowStatusId", "status", "dueAt", "contentItemId", "contentItemTitle", "assignees", "tags", "createdBy", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "descriptionDoc": { "anyOf": [ { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "workflowStatusId": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string", "enum": [ "todo", "in_progress", "done" ] }, "dueAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentItemId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "contentItemTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assignees": { "type": "array", "items": { "type": "object", "required": [ "userId", "name", "email" ], "properties": { "userId": { "$ref": "#/components/schemas/UUID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "colour" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" } }, "additionalProperties": false } }, "createdBy": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Fetch one task with its assignees, tags, and attached-post title.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tasks.getTask({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n taskId: process.env.OCTOSPARK_TASK_ID ?? \"taskId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tasks.get_task(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n taskId=os.environ.get(\"OCTOSPARK_TASK_ID\", \"taskId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tasks get-task \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"taskId\":\"taskId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let task_id = env::var(\"OCTOSPARK_TASK_ID\").unwrap_or_else(|_| \"taskId\".to_string());\n let url = format!(\"{}/v1/teams/{}/tasks/{}\", base_url.trim_end_matches('/'), team_id, task_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final taskId = Platform.environment['OCTOSPARK_TASK_ID'] ?? 'taskId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/tasks/$taskId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Task", "x-displayName": "Task" }, "patch": { "tags": [ "Tasks" ], "operationId": "tasks.updateTask", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "taskId", "in": "path", "schema": { "type": "string", "description": "Task id (UUID), as returned by the list/create task endpoints." }, "required": true, "description": "Task id (UUID), as returned by the list/create task endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "title", "description", "descriptionDoc", "workflowStatusId", "status", "dueAt", "contentItemId", "contentItemTitle", "assignees", "tags", "createdBy", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "descriptionDoc": { "anyOf": [ { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "workflowStatusId": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string", "enum": [ "todo", "in_progress", "done" ] }, "dueAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentItemId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "contentItemTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assignees": { "type": "array", "items": { "type": "object", "required": [ "userId", "name", "email" ], "properties": { "userId": { "$ref": "#/components/schemas/UUID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "colour" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" } }, "additionalProperties": false } }, "createdBy": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Partially update a task. assigneeUserIds/tagIds are full replacement sets when present (empty array clears); null clears dueAt, description, or the attached post. Moving workflowStatusId is how board drag-and-drop persists.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "title": { "type": "string", "description": "New title for the task, 1-500 characters. Omit to leave unchanged.", "title": "maxLength(500)", "minLength": 1, "maxLength": 500 }, "description": { "anyOf": [ { "type": "string", "description": "a string at most 10000 character(s) long", "title": "maxLength(10000)", "maxLength": 10000 }, { "type": "null" } ], "description": "Plain-text description used for search, card excerpts, and previews. Send null to clear it; omit to leave unchanged." }, "descriptionDoc": { "anyOf": [ { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ], "description": "Rich (block-based) description document, stored verbatim for the task editor. Send null to clear it. Keep the plain-text description field in sync for search and previews." }, "workflowStatusId": { "type": "string", "description": "Workspace-owned task workflow status id. Omit on create to use the first not_started task status.", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "status": { "type": "string", "enum": [ "todo", "in_progress", "done" ], "description": "Legacy task-state projection retained for checklist and summary compatibility. The workspace workflow status is authoritative." }, "dueAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 instant the task is due. Send null to clear the due date; tasks with a due date also appear on the calendar." }, "contentItemId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ], "description": "Id of the post this task is attached to (its checklist), as returned by the list posts endpoint. Send null to detach; attached tasks are removed with their post." }, "assigneeUserIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Full replacement set of team-member user ids assigned to the task; an empty array clears every assignment. Non-members are silently ignored." }, "tagIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Full replacement set of registry tag ids on the task (same registry as post tags); an empty array clears them. Tags from other teams are silently ignored." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tasks.updateTask({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n taskId: process.env.OCTOSPARK_TASK_ID ?? \"taskId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tasks.update_task(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n taskId=os.environ.get(\"OCTOSPARK_TASK_ID\", \"taskId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tasks update-task \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"taskId\":\"taskId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let task_id = env::var(\"OCTOSPARK_TASK_ID\").unwrap_or_else(|_| \"taskId\".to_string());\n let url = format!(\"{}/v1/teams/{}/tasks/{}\", base_url.trim_end_matches('/'), team_id, task_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final taskId = Platform.environment['OCTOSPARK_TASK_ID'] ?? 'taskId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/tasks/$taskId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Update task", "x-displayName": "Update task" }, "delete": { "tags": [ "Tasks" ], "operationId": "tasks.deleteTask", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "taskId", "in": "path", "schema": { "type": "string", "description": "Task id (UUID), as returned by the list/create task endpoints." }, "required": true, "description": "Task id (UUID), as returned by the list/create task endpoints." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Delete a task. Assignee and tag associations are removed with it; the attached post (if any) is unaffected. This cannot be undone.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tasks.deleteTask({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n taskId: process.env.OCTOSPARK_TASK_ID ?? \"taskId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tasks.delete_task(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n taskId=os.environ.get(\"OCTOSPARK_TASK_ID\", \"taskId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tasks delete-task \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"taskId\":\"taskId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let task_id = env::var(\"OCTOSPARK_TASK_ID\").unwrap_or_else(|_| \"taskId\".to_string());\n let url = format!(\"{}/v1/teams/{}/tasks/{}\", base_url.trim_end_matches('/'), team_id, task_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final taskId = Platform.environment['OCTOSPARK_TASK_ID'] ?? 'taskId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/tasks/$taskId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete task", "x-displayName": "Delete task" } }, "/v1/teams/{teamId}/tasks/summary": { "get": { "tags": [ "Tasks" ], "operationId": "tasks.getTaskSummary", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "contentItemId", "in": "query", "schema": { "type": "string", "description": "Restrict the per-status totals to tasks attached to this post." }, "required": false, "description": "Restrict the per-status totals to tasks attached to this post." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "todo", "inProgress", "done" ], "properties": { "todo": { "type": "number" }, "inProgress": { "type": "number" }, "done": { "type": "number" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Per-status task totals (to do / in progress / done) for the whole team, independent of any list filter, so board column headers can show live counts. Optionally scoped to one post via contentItemId.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.tasks.getTaskSummary({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.tasks.get_task_summary(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark tasks get-task-summary \\\n --request '{\"path\":{\"teamId\":\"teamId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/tasks/summary\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/tasks/summary';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Task summary", "x-displayName": "Task summary" } }, "/v1/teams/{teamId}/workflow-statuses": { "get": { "tags": [ "Workflow statuses" ], "operationId": "workflowStatuses.listWorkflowStatuses", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "appliesTo", "in": "query", "schema": { "type": "string", "enum": [ "content", "task" ], "description": "Registry to list: content statuses organize posts, while task statuses organize tasks." }, "required": true, "description": "Registry to list: content statuses organize posts, while task statuses organize tasks." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "name", "colour", "position", "appliesTo", "category", "autoPostEligible", "isTerminal", "createdAt", "updatedAt", "usageCount" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" }, "position": { "type": "number" }, "appliesTo": { "type": "string", "enum": [ "content", "task" ] }, "category": { "type": "string", "enum": [ "not_started", "active", "in_review", "completed", "closed" ] }, "autoPostEligible": { "type": "boolean" }, "isTerminal": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "usageCount": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "List the workspace workflow statuses for posts or tasks in display order. Each result includes its stable behavior category and current usage count.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.workflowStatuses.listWorkflowStatuses({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n query: {\n \"appliesTo\": process.env.OCTOSPARK_APPLIES_TO ?? \"appliesTo\",\n },\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.workflow_statuses.list_workflow_statuses(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n query={\n \"appliesTo\": os.environ.get(\"OCTOSPARK_APPLIES_TO\", \"appliesTo\"),\n }\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark workflow-statuses list-workflow-statuses \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"query\":{\"appliesTo\":\"appliesTo\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let applies_to = env::var(\"OCTOSPARK_APPLIES_TO\").unwrap_or_else(|_| \"appliesTo\".to_string());\n let url = format!(\"{}/v1/teams/{}/workflow-statuses\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.get(url).bearer_auth(token);\n let query = [(\"appliesTo\", applies_to.as_str())];\n request = request.query(&query);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final appliesTo = Platform.environment['OCTOSPARK_APPLIES_TO'] ?? 'appliesTo';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/workflow-statuses';\n final uri = Uri.parse(url).replace(queryParameters: {\n 'appliesTo': appliesTo,\n });\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.get(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "List workflow statuses", "x-displayName": "List workflow statuses" }, "post": { "tags": [ "Workflow statuses" ], "operationId": "workflowStatuses.createWorkflowStatus", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "name", "colour", "position", "appliesTo", "category", "autoPostEligible", "isTerminal", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" }, "position": { "type": "number" }, "appliesTo": { "type": "string", "enum": [ "content", "task" ] }, "category": { "type": "string", "enum": [ "not_started", "active", "in_review", "completed", "closed" ] }, "autoPostEligible": { "type": "boolean" }, "isTerminal": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Create a custom workflow status in the post or task registry. Required category coverage is preserved, task statuses cannot enable automatic publishing, and reserved runtime names are rejected.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "appliesTo", "name", "colour", "category" ], "properties": { "appliesTo": { "type": "string", "enum": [ "content", "task" ], "description": "Registry that will own this status. Use content for posts or task for tasks." }, "name": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "colour": { "type": "string", "description": "a string at most 32 character(s) long", "title": "maxLength(32)", "minLength": 1, "maxLength": 32 }, "position": { "type": "integer", "description": "Board column order. Omit to append the status to the end of the board.", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, "category": { "type": "string", "enum": [ "not_started", "active", "in_review", "completed", "closed" ], "description": "Stable behavior category for this status. Names can change, but category drives workflow rules." }, "autoPostEligible": { "type": "boolean", "description": "Whether this content status can trigger automatic publishing. Defaults to false." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.workflowStatuses.createWorkflowStatus({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.workflow_statuses.create_workflow_status(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark workflow-statuses create-workflow-status \\\n --request '{\"path\":{\"teamId\":\"teamId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let url = format!(\"{}/v1/teams/{}/workflow-statuses\", base_url.trim_end_matches('/'), team_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.post(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/workflow-statuses';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.post(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Create workflow status", "x-displayName": "Create workflow status" } }, "/v1/teams/{teamId}/workflow-statuses/{statusId}": { "patch": { "tags": [ "Workflow statuses" ], "operationId": "workflowStatuses.updateWorkflowStatus", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "statusId", "in": "path", "schema": { "type": "string", "description": "Workflow status id from the workspace registry." }, "required": true, "description": "Workflow status id from the workspace registry." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "teamId", "name", "colour", "position", "appliesTo", "category", "autoPostEligible", "isTerminal", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string" }, "colour": { "type": "string" }, "position": { "type": "number" }, "appliesTo": { "type": "string", "enum": [ "content", "task" ] }, "category": { "type": "string", "enum": [ "not_started", "active", "in_review", "completed", "closed" ] }, "autoPostEligible": { "type": "boolean" }, "isTerminal": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Rename, recolor, reorder, or recategorize a workflow status. The update is rejected if it would break required category coverage.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "colour": { "type": "string", "description": "a string at most 32 character(s) long", "title": "maxLength(32)", "minLength": 1, "maxLength": 32 }, "position": { "type": "integer", "description": "a non-negative number", "title": "greaterThanOrEqualTo(0)", "minimum": 0 }, "category": { "type": "string", "enum": [ "not_started", "active", "in_review", "completed", "closed" ], "description": "New stable behavior category. Omit to keep the current category." }, "autoPostEligible": { "type": "boolean", "description": "Whether this content status can trigger automatic publishing. Omit to keep the current value." } }, "additionalProperties": false } } }, "required": true }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.workflowStatuses.updateWorkflowStatus({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n statusId: process.env.OCTOSPARK_STATUS_ID ?? \"statusId\",\n body: {},\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.workflow_statuses.update_workflow_status(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n statusId=os.environ.get(\"OCTOSPARK_STATUS_ID\", \"statusId\"),\n body={}\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark workflow-statuses update-workflow-status \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"statusId\":\"statusId\"},\"body\":{}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let status_id = env::var(\"OCTOSPARK_STATUS_ID\").unwrap_or_else(|_| \"statusId\".to_string());\n let url = format!(\"{}/v1/teams/{}/workflow-statuses/{}\", base_url.trim_end_matches('/'), team_id, status_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.patch(url).bearer_auth(token);\n request = request.json(&serde_json::json!({}));\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final statusId = Platform.environment['OCTOSPARK_STATUS_ID'] ?? 'statusId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/workflow-statuses/$statusId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n 'Content-Type': 'application/json',\n };\n final response = await http.patch(\n uri,\n headers: headers,\n body: jsonEncode({}),\n );\n print(response.body);\n}" } ], "summary": "Update workflow status", "x-displayName": "Update workflow status" }, "delete": { "tags": [ "Workflow statuses" ], "operationId": "workflowStatuses.deleteWorkflowStatus", "parameters": [ { "name": "teamId", "in": "path", "schema": { "type": "string", "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, "required": true, "description": "Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context." }, { "name": "statusId", "in": "path", "schema": { "type": "string", "description": "Workflow status id from the workspace registry." }, "required": true, "description": "Workflow status id from the workspace registry." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } }, "additionalProperties": false } } } }, "400": { "description": "The request did not match the expected schema", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HttpApiDecodeError" }, { "$ref": "#/components/schemas/BadRequest" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unauthorized" } } } }, "402": { "description": "PaymentRequired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Forbidden" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "UnprocessableEntity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableEntity" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Delete a workflow status from the workspace registry. Required category coverage is preserved, and posts or tasks themselves are never deleted.", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript client", "source": "import { OctosparkClient } from '@octospark/sdk'\n\nconst client = new OctosparkClient({\n token: process.env.OCTOSPARK_TOKEN\n})\n\nconst response = await client.workflowStatuses.deleteWorkflowStatus({\n teamId: process.env.OCTOSPARK_TEAM_ID ?? \"teamId\",\n statusId: process.env.OCTOSPARK_STATUS_ID ?? \"statusId\",\n})" }, { "lang": "python", "label": "Python client", "source": "import os\nfrom octospark_sdk import OctosparkClient\n\nclient = OctosparkClient(token=os.environ[\"OCTOSPARK_TOKEN\"])\n\nresponse = client.workflow_statuses.delete_workflow_status(\n teamId=os.environ.get(\"OCTOSPARK_TEAM_ID\", \"teamId\"),\n statusId=os.environ.get(\"OCTOSPARK_STATUS_ID\", \"statusId\")\n)" }, { "lang": "CLI", "label": "CLI", "source": "octospark workflow-statuses delete-workflow-status \\\n --request '{\"path\":{\"teamId\":\"teamId\",\"statusId\":\"statusId\"}}'" }, { "lang": "rust", "label": "Rust", "source": "use reqwest::Client;\nuse std::env;\n\n#[tokio::main]\nasync fn main() -> Result<(), reqwest::Error> {\n let client = Client::new();\n let base_url = env::var(\"OCTOSPARK_API_URL\").unwrap_or_else(|_| \"https://api.octospark.ai\".to_string());\n let team_id = env::var(\"OCTOSPARK_TEAM_ID\").unwrap_or_else(|_| \"teamId\".to_string());\n let status_id = env::var(\"OCTOSPARK_STATUS_ID\").unwrap_or_else(|_| \"statusId\".to_string());\n let url = format!(\"{}/v1/teams/{}/workflow-statuses/{}\", base_url.trim_end_matches('/'), team_id, status_id);\n let token = env::var(\"OCTOSPARK_TOKEN\").expect(\"OCTOSPARK_TOKEN\");\n let mut request = client.delete(url).bearer_auth(token);\n let response = request.send().await?;\n println!(\"{}\", response.text().await?);\n Ok(())\n}" }, { "lang": "dart", "label": "Dart", "source": "import 'dart:convert';\nimport 'dart:io';\nimport 'package:http/http.dart' as http;\n\nFuture main() async {\n final baseUrl = Platform.environment['OCTOSPARK_API_URL'] ?? 'https://api.octospark.ai';\n final token = Platform.environment['OCTOSPARK_TOKEN'];\n final teamId = Platform.environment['OCTOSPARK_TEAM_ID'] ?? 'teamId';\n final statusId = Platform.environment['OCTOSPARK_STATUS_ID'] ?? 'statusId';\n final url = '${baseUrl.replaceFirst(RegExp(r'/$'), '')}/v1/teams/$teamId/workflow-statuses/$statusId';\n final uri = Uri.parse(url);\n final headers = {\n 'Authorization': 'Bearer $token',\n };\n final response = await http.delete(\n uri,\n headers: headers,\n );\n print(response.body);\n}" } ], "summary": "Delete workflow status", "x-displayName": "Delete workflow status" } } }, "components": { "schemas": { "HttpApiDecodeError": { "type": "object", "required": [ "issues", "message", "_tag" ], "properties": { "issues": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } }, "message": { "type": "string" }, "_tag": { "type": "string", "enum": [ "HttpApiDecodeError" ] } }, "additionalProperties": false, "description": "The request did not match the expected schema" }, "Issue": { "type": "object", "required": [ "_tag", "path", "message" ], "properties": { "_tag": { "type": "string", "enum": [ "Pointer", "Unexpected", "Missing", "Composite", "Refinement", "Transformation", "Type", "Forbidden" ], "description": "The tag identifying the type of parse issue" }, "path": { "type": "array", "items": { "$ref": "#/components/schemas/PropertyKey" }, "description": "The path to the property where the issue occurred" }, "message": { "type": "string", "description": "A descriptive message explaining the issue" } }, "additionalProperties": false, "description": "Represents an error encountered while parsing a value to match the schema" }, "PropertyKey": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "object", "required": [ "_tag", "key" ], "properties": { "_tag": { "type": "string", "enum": [ "symbol" ] }, "key": { "type": "string" } }, "additionalProperties": false, "description": "an object to be decoded into a globally shared symbol" } ] }, "BadRequest": { "type": "object", "required": [ "message", "_tag" ], "properties": { "message": { "type": "string" }, "_tag": { "type": "string", "enum": [ "BadRequest" ] } }, "additionalProperties": false }, "Unauthorized": { "type": "object", "required": [ "message", "_tag" ], "properties": { "message": { "type": "string" }, "_tag": { "type": "string", "enum": [ "Unauthorized" ] } }, "additionalProperties": false }, "PaymentRequired": { "type": "object", "required": [ "message", "_tag" ], "properties": { "message": { "type": "string" }, "_tag": { "type": "string", "enum": [ "PaymentRequired" ] } }, "additionalProperties": false }, "Forbidden": { "type": "object", "required": [ "message", "_tag" ], "properties": { "message": { "type": "string" }, "_tag": { "type": "string", "enum": [ "Forbidden" ] } }, "additionalProperties": false }, "NotFound": { "type": "object", "required": [ "message", "_tag" ], "properties": { "message": { "type": "string" }, "_tag": { "type": "string", "enum": [ "NotFound" ] } }, "additionalProperties": false }, "Conflict": { "type": "object", "required": [ "message", "_tag" ], "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "currentRevision": { "$ref": "#/components/schemas/Int" }, "_tag": { "type": "string", "enum": [ "Conflict" ] } }, "additionalProperties": false }, "Int": { "type": "integer", "description": "an integer", "title": "int" }, "UnprocessableEntity": { "type": "object", "required": [ "message", "code", "_tag" ], "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "_tag": { "type": "string", "enum": [ "UnprocessableEntity" ] } }, "additionalProperties": false }, "TooManyRequests": { "type": "object", "required": [ "message", "_tag" ], "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "retryAfterSeconds": { "$ref": "#/components/schemas/Int" }, "_tag": { "type": "string", "enum": [ "TooManyRequests" ] } }, "additionalProperties": false }, "InternalError": { "type": "object", "required": [ "message", "_tag" ], "properties": { "message": { "type": "string" }, "_tag": { "type": "string", "enum": [ "InternalError" ] } }, "additionalProperties": false }, "UUID": { "type": "string", "description": "a Universally Unique Identifier", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "SeedVisualEnrichment": { "type": "object", "required": [ "title", "description", "tags", "subjects", "actions", "scenarios", "emotions", "captionGuidance", "categories", "promptVersion", "sourceHash", "model", "requestedModel", "mediaInput", "generationId", "generatedAt" ], "properties": { "title": { "type": "string", "description": "a string at most 160 character(s) long", "title": "maxLength(160)", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "description": "a string at most 1200 character(s) long", "title": "maxLength(1200)", "minLength": 1, "maxLength": 1200 }, "tags": { "type": "array", "items": { "type": "string", "description": "a string at most 160 character(s) long", "title": "maxLength(160)", "minLength": 1, "maxLength": 160 }, "description": "an array of at most 6 item(s)", "title": "maxItems(6)", "maxItems": 6 }, "subjects": { "type": "array", "items": { "type": "string", "description": "a string at most 160 character(s) long", "title": "maxLength(160)", "minLength": 1, "maxLength": 160 }, "description": "an array of at most 6 item(s)", "title": "maxItems(6)", "maxItems": 6 }, "actions": { "type": "array", "items": { "type": "string", "description": "a string at most 160 character(s) long", "title": "maxLength(160)", "minLength": 1, "maxLength": 160 }, "description": "an array of at most 6 item(s)", "title": "maxItems(6)", "maxItems": 6 }, "scenarios": { "type": "array", "items": { "type": "string", "description": "a string at most 160 character(s) long", "title": "maxLength(160)", "minLength": 1, "maxLength": 160 }, "description": "an array of at most 6 item(s)", "title": "maxItems(6)", "maxItems": 6 }, "emotions": { "type": "array", "items": { "type": "string", "description": "a string at most 160 character(s) long", "title": "maxLength(160)", "minLength": 1, "maxLength": 160 }, "description": "an array of at most 6 item(s)", "title": "maxItems(6)", "maxItems": 6 }, "captionGuidance": { "type": "string", "description": "a string at most 1000 character(s) long", "title": "maxLength(1000)", "minLength": 1, "maxLength": 1000 }, "categories": { "type": "array", "items": { "type": "string", "description": "a string at most 160 character(s) long", "title": "maxLength(160)", "minLength": 1, "maxLength": 160 }, "description": "an array of at most 4 item(s)", "title": "maxItems(4)", "minItems": 1, "maxItems": 4 }, "promptVersion": { "type": "number", "enum": [ 1 ] }, "sourceHash": { "type": "string", "description": "a string matching the pattern ^[a-f0-9]{64}$", "pattern": "^[a-f0-9]{64}$" }, "model": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "requestedModel": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaInput": { "type": "string", "enum": [ "image", "video" ] }, "generationId": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "generatedAt": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 } }, "additionalProperties": false }, "SeedVisualEnrichmentFailure": { "type": "object", "required": [ "promptVersion", "sourceHash", "model", "requestedModel", "mediaInput", "reason", "generationId", "attemptedAt" ], "properties": { "promptVersion": { "type": "number", "enum": [ 1 ] }, "sourceHash": { "type": "string", "description": "a string matching the pattern ^[a-f0-9]{64}$", "pattern": "^[a-f0-9]{64}$" }, "model": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "requestedModel": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 }, "mediaInput": { "type": "string", "enum": [ "image", "video" ] }, "reason": { "type": "string", "enum": [ "provider_content_filter" ] }, "embeddingSource": { "type": "string", "enum": [ "source_metadata" ] }, "generationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attemptedAt": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 } }, "additionalProperties": false }, "FolderDeleteBlocked": { "type": "object", "required": [ "message", "blockedAssets", "_tag" ], "properties": { "message": { "type": "string" }, "blockedAssets": { "type": "array", "items": { "type": "object", "required": [ "assetId", "originalFilename", "scheduledPostIds" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "originalFilename": { "type": "string" }, "scheduledPostIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false } }, "_tag": { "type": "string", "enum": [ "FolderDeleteBlocked" ] } }, "additionalProperties": false }, "DateTimeUtc": { "type": "string", "description": "a string to be decoded into a DateTime.Utc" }, "ListAgentSchedulesResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSchedule" } } }, "additionalProperties": false }, "AgentSchedule": { "type": "object", "required": [ "id", "organizationId", "teamId", "name", "brief", "cadence", "nextRunAt", "lastRunAt", "perRunCreditCeilingDecimillicents", "dailyCreditCeilingDecimillicents", "pendingItemCap", "pausedAt", "createdBy", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "organizationId": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string", "description": "Display name for the automation, 1-120 characters.", "title": "maxLength(120)", "minLength": 1, "maxLength": 120 }, "brief": { "type": "string", "description": "The instruction the scheduled run starts from - the prompt handed to the agent.", "title": "maxLength(20000)", "minLength": 1, "maxLength": 20000 }, "cadence": { "type": "string", "description": "Five-field cron expression (minute hour day-of-month month day-of-week), evaluated in UTC. Invalid expressions are rejected 400.", "title": "maxLength(100)", "minLength": 1, "examples": [ "0 9 * * *", "*/30 * * * 1-5" ], "maxLength": 100 }, "nextRunAt": { "type": "string", "description": "When the schedule next fires (ISO-8601 UTC)." }, "lastRunAt": { "anyOf": [ { "type": "string", "description": "When the sweeper last fired this schedule (ISO-8601 UTC); null before the first run." }, { "type": "null" } ] }, "perRunCreditCeilingDecimillicents": { "$ref": "#/components/schemas/Int", "description": "Per-run credit ceiling in decimillicents. A scheduled run stops (incomplete, surfaced in the inbox) when it reaches this spend.", "title": "positive", "exclusiveMinimum": 0 }, "dailyCreditCeilingDecimillicents": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "Optional daily credit ceiling in decimillicents across all of this schedule's runs (UTC day). The sweeper skips firing once reached; null means no daily ceiling.", "title": "positive", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Optional daily credit ceiling in decimillicents across all of this schedule's runs (UTC day). The sweeper skips firing once reached; send null for no daily ceiling." }, "pendingItemCap": { "$ref": "#/components/schemas/Int", "description": "Skip firing while this many (or more) of the schedule's runs sit unreviewed in the inbox, 1-100 (default 10). Keeps a broken automation from flooding the queue.", "title": "lessThanOrEqualTo(100)", "minimum": 1, "maximum": 100 }, "pausedAt": { "anyOf": [ { "type": "string", "description": "When the schedule was paused (ISO-8601 UTC); null while active. A paused schedule never fires." }, { "type": "null" } ] }, "createdBy": { "$ref": "#/components/schemas/UUID" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, "CreateAgentScheduleBody": { "type": "object", "required": [ "name", "brief", "cadence" ], "properties": { "name": { "type": "string", "description": "Display name for the automation, 1-120 characters.", "title": "maxLength(120)", "minLength": 1, "maxLength": 120 }, "brief": { "type": "string", "description": "The instruction the scheduled run starts from - the prompt handed to the agent.", "title": "maxLength(20000)", "minLength": 1, "maxLength": 20000 }, "cadence": { "type": "string", "description": "Five-field cron expression (minute hour day-of-month month day-of-week), evaluated in UTC. Invalid expressions are rejected 400.", "title": "maxLength(100)", "minLength": 1, "examples": [ "0 9 * * *", "*/30 * * * 1-5" ], "maxLength": 100 }, "perRunCreditCeilingDecimillicents": { "$ref": "#/components/schemas/Int", "description": "Per-run credit ceiling in decimillicents. A scheduled run stops (incomplete, surfaced in the inbox) when it reaches this spend. Omit for the default of $100 per run (1000000000 decimillicents).", "title": "positive", "exclusiveMinimum": 0 }, "dailyCreditCeilingDecimillicents": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "Optional daily credit ceiling in decimillicents across all of this schedule's runs (UTC day). The sweeper skips firing once reached; null means no daily ceiling.", "title": "positive", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Daily credit ceiling in decimillicents across all of this schedule's runs (UTC day). The sweeper skips firing once reached. Omit for the default of $100 per day (1000000000 decimillicents); send null explicitly for no daily ceiling." }, "pendingItemCap": { "$ref": "#/components/schemas/Int", "description": "Skip firing while this many (or more) of the schedule's runs sit unreviewed in the inbox, 1-100 (default 10). Keeps a broken automation from flooding the queue.", "title": "lessThanOrEqualTo(100)", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "UpdateAgentScheduleBody": { "type": "object", "required": [], "properties": { "name": { "type": "string", "description": "Display name for the automation, 1-120 characters.", "title": "maxLength(120)", "minLength": 1, "maxLength": 120 }, "brief": { "type": "string", "description": "The instruction the scheduled run starts from - the prompt handed to the agent.", "title": "maxLength(20000)", "minLength": 1, "maxLength": 20000 }, "cadence": { "type": "string", "description": "Five-field cron expression (minute hour day-of-month month day-of-week), evaluated in UTC. Invalid expressions are rejected 400.", "title": "maxLength(100)", "minLength": 1, "examples": [ "0 9 * * *", "*/30 * * * 1-5" ], "maxLength": 100 }, "perRunCreditCeilingDecimillicents": { "$ref": "#/components/schemas/Int", "description": "Per-run credit ceiling in decimillicents. A scheduled run stops (incomplete, surfaced in the inbox) when it reaches this spend.", "title": "positive", "exclusiveMinimum": 0 }, "dailyCreditCeilingDecimillicents": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "Optional daily credit ceiling in decimillicents across all of this schedule's runs (UTC day). The sweeper skips firing once reached; null means no daily ceiling.", "title": "positive", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Optional daily credit ceiling in decimillicents across all of this schedule's runs (UTC day). The sweeper skips firing once reached; send null for no daily ceiling." }, "pendingItemCap": { "$ref": "#/components/schemas/Int", "description": "Skip firing while this many (or more) of the schedule's runs sit unreviewed in the inbox, 1-100 (default 10). Keeps a broken automation from flooding the queue.", "title": "lessThanOrEqualTo(100)", "minimum": 1, "maximum": 100 }, "paused": { "type": "boolean", "description": "true pauses the schedule (stamps pausedAt), false resumes it. Omit to leave the pause state unchanged." } }, "additionalProperties": false }, "ListContentRendersResponse": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MediaRenderListItem" } }, "total": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 } }, "additionalProperties": false, "description": "A page of matching durable renders and the total across the same tenant-scoped filters." }, "MediaRenderListItem": { "type": "object", "required": [ "kind", "id", "contentItemId", "title", "artifactKind", "artifactRunId", "renderJobId", "status", "outputAssetIds", "payloadRevision", "creativeHash", "outputWidth", "outputHeight", "slideCount", "createdAt", "startedAt", "completedAt", "updatedAt", "outputs", "previewUrl" ], "properties": { "kind": { "type": "string", "enum": [ "render_job", "artifact_run" ] }, "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "artifactKind": { "type": "string", "enum": [ "slideshow", "image_meme", "green_screen_meme" ] }, "artifactRunId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "renderJobId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "queued", "running", "repairing", "pre_render_complete", "paused", "cancel_requested", "succeeded", "failed", "cancelled", "superseded", "queued", "validating", "rendering", "uploading", "succeeded", "failed", "cancel_requested", "cancelled", "superseded" ] }, "outputAssetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "payloadRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "creativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outputWidth": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "outputHeight": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "slideCount": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/MediaRenderOutputAsset" } }, "previewUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "A durable run or render job with eligible team-owned output metadata and a fresh preview URL where available." }, "MediaRenderOutputAsset": { "type": "object", "required": [ "id", "filename", "mimeType", "assetType", "fileSizeBytes", "width", "height", "durationSeconds" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "assetType": { "type": "string", "enum": [ "image", "video", "audio", "gif", "document" ] }, "fileSizeBytes": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "width": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "height": { "anyOf": [ { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "durationSeconds": { "anyOf": [ { "type": "number", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Eligible canonical output media metadata, without source files, session data or template calibration details." }, "ListContentRenderJobsResponse": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MediaQueueItem" } }, "total": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "MediaQueueItem": { "type": "object", "required": [ "kind", "id", "contentItemId", "title", "artifactKind", "artifactRunId", "renderJobId", "status", "outputAssetIds", "payloadRevision", "creativeHash", "outputWidth", "outputHeight", "slideCount", "createdAt", "startedAt", "completedAt", "updatedAt" ], "properties": { "kind": { "type": "string", "enum": [ "render_job", "artifact_run" ] }, "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "artifactKind": { "type": "string", "enum": [ "slideshow", "image_meme", "green_screen_meme" ] }, "artifactRunId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "renderJobId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "queued", "running", "repairing", "pre_render_complete", "paused", "cancel_requested", "succeeded", "failed", "cancelled", "superseded", "queued", "validating", "rendering", "uploading", "succeeded", "failed", "cancel_requested", "cancelled", "superseded" ] }, "outputAssetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "payloadRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "creativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outputWidth": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "outputHeight": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "slideCount": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, "DeleteSlideshowResponse": { "type": "object", "required": [ "contentItemId", "deleted", "revision", "cancelledArtifactRunIds", "cancelledRenderJobIds" ], "properties": { "contentItemId": { "$ref": "#/components/schemas/UUID" }, "deleted": { "type": "boolean", "enum": [ true ] }, "revision": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "cancelledArtifactRunIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "cancelledRenderJobIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } } }, "additionalProperties": false }, "SlideshowChatResponse": { "type": "object", "required": [ "conversationId", "messages" ], "properties": { "conversationId": { "$ref": "#/components/schemas/UUID" }, "messages": { "type": "array", "items": { "type": "object", "required": [ "id", "runId", "role", "text", "createdAt" ], "properties": { "id": { "type": "string" }, "runId": { "$ref": "#/components/schemas/UUID" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "text": { "type": "string" }, "createdAt": { "type": "string" }, "parts": { "type": "array", "items": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } } } }, "additionalProperties": false } } }, "additionalProperties": false }, "MediaRunBundleResponse": { "type": "object", "required": [ "runId", "availability", "input", "latestCheckpoint", "result", "latestSuggestion" ], "properties": { "runId": { "$ref": "#/components/schemas/UUID" }, "availability": { "type": "string", "enum": [ "pending", "available", "expired" ] }, "input": { "anyOf": [ { "$ref": "#/components/schemas/MediaRunSnapshot" }, { "type": "null" } ] }, "latestCheckpoint": { "anyOf": [ { "$ref": "#/components/schemas/MediaRunSnapshot" }, { "type": "null" } ] }, "result": { "anyOf": [ { "$ref": "#/components/schemas/MediaRunSnapshot" }, { "type": "null" } ] }, "latestSuggestion": { "anyOf": [ { "$ref": "#/components/schemas/MediaRunSnapshot" }, { "type": "null" } ] } }, "additionalProperties": false }, "MediaRunSnapshot": { "type": "object", "required": [ "id", "runId", "kind", "sequenceNumber", "sha256", "bundle", "createdAt", "expiresAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "runId": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "input", "checkpoint", "result", "suggestion" ] }, "sequenceNumber": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, "sha256": { "type": "string", "description": "a string matching the pattern ^[a-f0-9]{64}$", "pattern": "^[a-f0-9]{64}$" }, "bundle": { "$ref": "#/components/schemas/MediaRunBundle" }, "browserPreviewUrl": { "type": "string" }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" } }, "additionalProperties": false }, "MediaRunBundle": { "type": "object", "required": [ "version", "type", "runId", "promptVersion", "harnessVersion", "toolVersions", "runtimeImageDigest", "sourceFiles", "dependencyLockfile", "assetManifest", "input", "output", "createdAt" ], "properties": { "version": { "type": "number", "enum": [ 1 ] }, "type": { "type": "string", "enum": [ "slideshow", "animated_video", "image_meme", "green_screen_meme" ] }, "runId": { "$ref": "#/components/schemas/UUID" }, "promptVersion": { "type": "string", "description": "a string at most 256 character(s) long", "title": "maxLength(256)", "minLength": 1, "maxLength": 256 }, "harnessVersion": { "type": "string", "description": "a string at most 256 character(s) long", "title": "maxLength(256)", "minLength": 1, "maxLength": 256 }, "toolVersions": { "type": "object", "required": [], "properties": {}, "patternProperties": { "": { "type": "string", "description": "a string at most 256 character(s) long", "title": "maxLength(256)", "minLength": 1, "maxLength": 256 } }, "propertyNames": { "type": "string", "description": "a string at most 256 character(s) long", "title": "maxLength(256)", "minLength": 1, "maxLength": 256 } }, "runtimeImageDigest": { "type": "string", "description": "a string at most 256 character(s) long", "title": "maxLength(256)", "minLength": 1, "maxLength": 256 }, "sourceFiles": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowSourceFileV1" }, "description": "an array of at most 64 item(s)", "title": "maxItems(64)", "maxItems": 64 }, "dependencyLockfile": { "type": "string", "description": "a string at most 1000000 character(s) long", "title": "maxLength(1000000)", "maxLength": 1000000 }, "assetManifest": { "type": "array", "items": { "type": "object", "required": [ "mediaAssetId", "sha256", "path" ], "properties": { "mediaAssetId": { "$ref": "#/components/schemas/UUID" }, "sha256": { "type": "string", "description": "a string matching the pattern ^[a-f0-9]{64}$", "pattern": "^[a-f0-9]{64}$" }, "path": { "$ref": "#/components/schemas/SlideshowSourcePath" } }, "additionalProperties": false }, "description": "an array of at most 128 item(s)", "title": "maxItems(128)", "maxItems": 128 }, "input": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "output": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "project": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "session": { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" }, "description": "an array of at most 10000 item(s)", "title": "maxItems(10000)", "maxItems": 10000 }, "createdAt": { "type": "string", "description": "a string at least 1 character(s) long", "title": "minLength(1)", "minLength": 1 } }, "additionalProperties": false }, "SlideshowSourceFileV1": { "type": "object", "required": [ "path", "contents", "sha256" ], "properties": { "path": { "type": "string", "description": "Normalised source file path relative to the run bundle. Absolute paths and parent traversal are rejected." }, "contents": { "type": "string", "description": "a string at most 256000 character(s) long", "title": "maxLength(256000)", "maxLength": 256000 }, "sha256": { "$ref": "#/components/schemas/SlideshowSha256" } }, "additionalProperties": false }, "SlideshowSha256": { "type": "string", "description": "a string matching the pattern ^[a-f0-9]{64}$", "pattern": "^[a-f0-9]{64}$" }, "SlideshowSourcePath": { "type": "string", "description": "Normalised source file path relative to the run bundle. Absolute paths and parent traversal are rejected." }, "SlideshowSourceForRunResponse": { "type": "object", "required": [ "runId", "availability", "input", "latestCheckpoint", "result", "latestSuggestion" ], "properties": { "runId": { "$ref": "#/components/schemas/UUID" }, "availability": { "type": "string", "enum": [ "pending", "available", "expired" ] }, "input": { "anyOf": [ { "$ref": "#/components/schemas/MediaRunSnapshot" }, { "type": "null" } ] }, "latestCheckpoint": { "anyOf": [ { "$ref": "#/components/schemas/MediaRunSnapshot" }, { "type": "null" } ] }, "result": { "anyOf": [ { "$ref": "#/components/schemas/MediaRunSnapshot" }, { "type": "null" } ] }, "latestSuggestion": { "anyOf": [ { "$ref": "#/components/schemas/MediaRunSnapshot" }, { "type": "null" } ] } }, "additionalProperties": false }, "SlideshowRegenerationScope": { "type": "string", "enum": [ "text", "image", "layout", "style", "all" ] }, "CreateSlideshowEditRunBody": { "type": "object", "required": [ "prompt", "expectedRevision" ], "properties": { "prompt": { "type": "string", "description": "a string at most 8000 character(s) long", "title": "maxLength(8000)", "minLength": 1, "maxLength": 8000 }, "expectedRevision": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, "model": { "type": "string", "enum": [ "google/gemini-3.8-flash", "anthropic/claude-opus-5.5", "openai/gpt-6-sol", "anthropic/claude-sonnet-5", "openai/gpt-6-luna", "x-ai/grok-4.7", "deepseek/deepseek-v4.1-flash", "qwen/qwen3.8-flash", "minimax/minimax-m3", "mistralai/mistral-small-2603", "moonshotai/kimi-k3", "xiaomi/mimo-v2.6-flash", "stepfun/step-3.7-flash", "google/gemini-3.7-flash", "anthropic/claude-opus-5", "openai/gpt-5.6-sol", "openai/gpt-5.6-terra", "x-ai/grok-4.6", "deepseek/deepseek-v4-flash-0731", "qwen/qwen3.7-plus", "moonshotai/kimi-k2.6", "xiaomi/mimo-v2.5", "google/gemini-3.5-flash", "anthropic/claude-opus-4.8", "google/gemini-3.1-pro-preview", "x-ai/grok-4.5" ], "description": "Text model for this slideshow edit. Omit to use the default. Provider failures may use a fallback; the actual model and cost are recorded." }, "reasoning": { "type": "object", "required": [], "properties": { "enabled": { "type": "boolean" }, "effort": { "type": "string", "enum": [ "max", "xhigh", "high", "medium", "low", "minimal", "none" ] } }, "additionalProperties": false, "description": "Reasoning preference supported by the selected model. Omit to use its default. Reasoning tokens may increase the edit cost." }, "selectedSourceIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Up to ten sources from this team to ground the edit. Omit for no additional sources.", "title": "maxItems(10)", "maxItems": 10 }, "referenceAssetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Up to ten owned images or videos to attach as references for the agent. Omit for no additional media.", "title": "maxItems(10)", "maxItems": 10 }, "visualChecks": { "type": "boolean", "description": "When true, render visual checks for the agent to inspect and polish the edit. Defaults to false; an interactive browser preview is still available." }, "autoRender": { "type": "boolean", "description": "When true, export the slideshow after the edit commits. Defaults to false; the edit remains an editable draft." }, "selection": { "type": "object", "required": [ "elementPath" ], "properties": { "elementPath": { "type": "string", "description": "a string at most 1024 character(s) long", "title": "maxLength(1024)", "minLength": 1, "maxLength": 1024 }, "sourcePath": { "$ref": "#/components/schemas/SlideshowSourcePath" }, "line": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, "frame": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "slideId": { "$ref": "#/components/schemas/UUID" }, "textElementId": { "$ref": "#/components/schemas/UUID" }, "bounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between -100000 and 100000", "title": "between(-100000, 100000)", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "description": "a number between -100000 and 100000", "title": "between(-100000, 100000)", "minimum": -100000, "maximum": 100000 }, "width": { "type": "number", "description": "a number between 0 and 100000", "title": "between(0, 100000)", "minimum": 0, "maximum": 100000 }, "height": { "type": "number", "description": "a number between 0 and 100000", "title": "between(0, 100000)", "minimum": 0, "maximum": 100000 } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Selected rendered element and its source location or bounds. Omit to edit the whole slideshow." } }, "additionalProperties": false }, "CreateSlideshowSourceRevisionBody": { "type": "object", "required": [ "expectedRevision", "sourceFiles" ], "properties": { "expectedRevision": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, "sourceFiles": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowSourceFileV1" }, "description": "an array of at most 64 item(s)", "title": "maxItems(64)", "minItems": 1, "maxItems": 64 }, "entryPoint": { "type": "string", "description": "Normalised source file path relative to the run bundle. Absolute paths and parent traversal are rejected." } }, "additionalProperties": false }, "GenerateSlideshowBody": { "type": "object", "required": [ "prompt" ], "properties": { "maxSpendDecimillicents": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 100000000", "title": "between(1, 100000000)", "minimum": 1, "maximum": 100000000 }, "defaultImageSource": { "anyOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "auto" ] }, "strategy": { "type": "string", "enum": [ "auto", "search", "generate" ] }, "searchProviders": { "type": "array", "items": { "type": "string", "enum": [ "pinterest", "unsplash" ] }, "description": "an array of at most 2 item(s)", "title": "maxItems(2)", "maxItems": 2 }, "generationRenderMode": { "type": "string", "enum": [ "background", "complete_slide" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "mode", "mediaAssetId" ], "properties": { "mode": { "type": "string", "enum": [ "media_asset" ] }, "mediaAssetId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false }, { "type": "object", "required": [ "mode", "imagePackId" ], "properties": { "mode": { "type": "string", "enum": [ "image_pack" ] }, "imagePackId": { "type": "string", "description": "a string at most 128 character(s) long", "title": "maxLength(128)", "minLength": 1, "maxLength": 128 }, "selection": { "type": "string", "enum": [ "auto", "sequential" ] } }, "additionalProperties": false } ], "description": "Default background source for slides: stock search, generated image, upload or a named library pack. Individual slides can override it." }, "imageModelId": { "type": "string", "description": "a string at most 256 character(s) long", "title": "maxLength(256)", "minLength": 1, "maxLength": 256 }, "prompt": { "type": "string", "description": "a string at most 8000 character(s) long", "title": "maxLength(8000)", "minLength": 1, "maxLength": 8000 }, "slideCount": { "$ref": "#/components/schemas/Int", "description": "a number between 2 and 20", "title": "between(2, 20)", "minimum": 2, "maximum": 20 }, "slideCountMode": { "$ref": "#/components/schemas/SlideshowGenerationSlideCountMode" }, "aspectRatio": { "type": "string", "enum": [ "4:5", "9:16", "1:1", "16:9" ], "description": "Requested output aspect ratio for every generated slide; defaults to 4:5." }, "brandId": { "$ref": "#/components/schemas/UUID" }, "model": { "type": "string", "enum": [ "google/gemini-3.8-flash", "anthropic/claude-opus-5.5", "openai/gpt-6-sol", "anthropic/claude-sonnet-5", "openai/gpt-6-luna", "x-ai/grok-4.7", "deepseek/deepseek-v4.1-flash", "qwen/qwen3.8-flash", "minimax/minimax-m3", "mistralai/mistral-small-2603", "moonshotai/kimi-k3", "xiaomi/mimo-v2.6-flash", "stepfun/step-3.7-flash", "google/gemini-3.7-flash", "anthropic/claude-opus-5", "openai/gpt-5.6-sol", "openai/gpt-5.6-terra", "x-ai/grok-4.6", "deepseek/deepseek-v4-flash-0731", "qwen/qwen3.7-plus", "moonshotai/kimi-k2.6", "xiaomi/mimo-v2.5", "google/gemini-3.5-flash", "anthropic/claude-opus-4.8", "google/gemini-3.1-pro-preview", "x-ai/grok-4.5" ], "description": "OpenRouter model to write the deck with. Omit to use the prompt registry default." }, "selectedSourceIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "an array of at most 50 item(s)", "title": "maxItems(50)", "maxItems": 50 }, "tone": { "$ref": "#/components/schemas/SlideshowGenerationTone" }, "language": { "$ref": "#/components/schemas/SlideshowGenerationLanguage" }, "captionDefaults": { "$ref": "#/components/schemas/SlideshowGenerationCaptionDefaults" }, "backgroundOverlay": { "$ref": "#/components/schemas/SlideshowGenerationBackgroundOverlay" }, "slideImageSources": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowGenerationSlideImageSource" }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 2, "maxItems": 20 }, "referenceAssetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "an array of at most 64 item(s)", "title": "maxItems(64)", "maxItems": 64 }, "referenceSlideshowIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "maxItems": 20 }, "styleBrief": { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, "templateMode": { "$ref": "#/components/schemas/SlideshowGenerationTemplateMode" }, "visualChecks": { "type": "boolean", "description": "When true, render visual checks for the agent to inspect and polish the slideshow. Defaults to false; an interactive browser preview is still available." }, "autoRender": { "type": "boolean", "description": "When true, export the generated slideshow as soon as generation completes. Defaults to false; generation leaves an editable draft." } }, "additionalProperties": false }, "SlideshowGenerationSlideCountMode": { "type": "string", "enum": [ "fixed", "automatic" ], "description": "Fixed uses the requested count. Automatic resolves a count from three to six from the brief." }, "SlideshowGenerationTone": { "type": "string", "enum": [ "educational", "personal" ], "description": "Narrative tone used for generated slide copy and visual direction. Defaults to educational." }, "SlideshowGenerationLanguage": { "type": "string", "enum": [ "same_as_prompt", "en", "es", "fr", "de", "it", "pt", "nl", "ja", "zh-TW", "zh-CN", "ko", "hi", "ar", "ru", "pl", "tr", "id", "sv", "da", "no", "fi" ], "description": "Language used for generated on-slide text. Defaults to the language detected from the prompt." }, "SlideshowGenerationCaptionDefaults": { "type": "object", "required": [ "preset", "fontFamily", "size", "width" ], "properties": { "preset": { "type": "string", "enum": [ "white_outline", "muted_dark_panel", "white_panel", "soft_shadow", "black_panel", "plain_dark" ] }, "fontFamily": { "type": "string", "enum": [ "TikTok Display", "Anton", "Arial", "Bebas Neue", "Bitcount", "Cinzel", "Della", "DynaPuff", "Eagle Lake", "Georgia", "Helvetica", "Inter", "Lexend", "Libre Baskerville", "Montserrat", "Noto Sans JP", "Noto Sans TC", "Open Sans", "Oswald", "Playwrite", "Poppins", "Public Sans", "Roboto", "Roboto Slab", "Rubik", "Russo One", "TikTok Sans", "Times New Roman" ] }, "size": { "type": "string", "enum": [ "normal", "small" ] }, "width": { "type": "string", "enum": [ "wide", "narrow" ] } }, "additionalProperties": false, "description": "Default caption preset, font, size, and width applied to generated editable slide text." }, "SlideshowGenerationBackgroundOverlay": { "type": "object", "required": [ "enabled", "hookEnabled", "opacity" ], "properties": { "enabled": { "type": "boolean" }, "hookEnabled": { "type": "boolean" }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false, "description": "Dark background overlay defaults for generated slides. The hook can be controlled independently." }, "SlideshowGenerationSlideImageSource": { "anyOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "auto" ] }, "strategy": { "type": "string", "enum": [ "auto", "search", "generate" ] }, "searchProviders": { "type": "array", "items": { "type": "string", "enum": [ "pinterest", "unsplash" ] }, "description": "an array of at most 2 item(s)", "title": "maxItems(2)", "maxItems": 2 }, "generationRenderMode": { "type": "string", "enum": [ "background", "complete_slide" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "mode", "mediaAssetId" ], "properties": { "mode": { "type": "string", "enum": [ "media_asset" ] }, "mediaAssetId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false }, { "type": "object", "required": [ "mode", "imagePackId" ], "properties": { "mode": { "type": "string", "enum": [ "image_pack" ] }, "imagePackId": { "type": "string", "description": "a string at most 128 character(s) long", "title": "maxLength(128)", "minLength": 1, "maxLength": 128 }, "selection": { "type": "string", "enum": [ "auto", "sequential" ] } }, "additionalProperties": false } ] }, "SlideshowGenerationTemplateMode": { "type": "string", "enum": [ "editable", "custom" ], "description": "Editable uses the structured renderer. Custom runs the bounded template builder with real render previews and a visual critic." }, "SlideshowArtifactRunResponse": { "type": "object", "required": [ "id", "contentItemId", "kind", "status", "targetSlideId", "regenerationScope", "baseRevision", "resultRevision", "workflowId", "renderJobId", "outputAssetId", "errorCode", "diagnostics", "pauseReason", "maxSpendDecimillicents", "spentDecimillicents", "activeDurationMs", "links" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "generation", "slide_regeneration", "edit" ] }, "status": { "type": "string" }, "targetSlideId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "regenerationScope": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowRegenerationScope" }, { "type": "null" } ] }, "baseRevision": { "$ref": "#/components/schemas/Int" }, "resultRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "workflowId": { "type": "string" }, "renderJobId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "outputAssetId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pauseReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxSpendDecimillicents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spentDecimillicents": { "type": "number" }, "activeDurationMs": { "type": "number" }, "links": { "type": "object", "required": [ "self", "events", "slideshow" ], "properties": { "self": { "type": "string" }, "events": { "type": "string" }, "slideshow": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "RetrySlideshowArtifactRunBody": { "type": "object", "required": [ "expectedRevision" ], "properties": { "expectedRevision": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "ContentJobEventsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "sequence", "eventName", "payload", "createdAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "sequence": { "$ref": "#/components/schemas/Int" }, "eventName": { "type": "string" }, "payload": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, "createdAt": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "ContentRenderJobDetailResponse": { "type": "object", "required": [ "id", "contentItemId", "artifactRunId", "payloadId", "payloadRevision", "creativeHash", "rendererVersion", "status", "workflowId", "outputWidth", "outputHeight", "slideCount", "pixelCount", "outputManifest", "durationMs", "hostId", "errorClass", "errorCode", "diagnostics", "retryable", "createdAt", "startedAt", "completedAt", "updatedAt", "projectSnapshot" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "artifactRunId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "payloadId": { "$ref": "#/components/schemas/UUID" }, "payloadRevision": { "$ref": "#/components/schemas/Int" }, "creativeHash": { "type": "string" }, "rendererVersion": { "type": "string" }, "status": { "type": "string" }, "workflowId": { "type": "string" }, "outputWidth": { "$ref": "#/components/schemas/Int" }, "outputHeight": { "$ref": "#/components/schemas/Int" }, "slideCount": { "$ref": "#/components/schemas/Int" }, "pixelCount": { "$ref": "#/components/schemas/Int" }, "outputManifest": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "durationMs": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "hostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorClass": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "projectSnapshot": { "$ref": "#/components/schemas/SlideshowProjectV1" } }, "additionalProperties": false }, "SlideshowProjectV1": { "type": "object", "required": [ "schemaVersion", "artifactKind", "runtime", "sourceFiles", "output", "slides", "styles", "assetBindings", "styleContext" ], "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "artifactKind": { "type": "string", "enum": [ "slideshow" ] }, "runtime": { "$ref": "#/components/schemas/SlideshowRuntimeV1" }, "sourceFiles": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowSourceFileV1" }, "description": "an array of at most 64 item(s)", "title": "maxItems(64)", "minItems": 1, "maxItems": 64 }, "output": { "$ref": "#/components/schemas/SlideshowOutputV1" }, "slides": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowSlideV1" }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 2, "maxItems": 20 }, "styles": { "$ref": "#/components/schemas/SlideshowStylesV1" }, "assetBindings": { "$ref": "#/components/schemas/SlideshowAssetBindingsV1" }, "styleContext": { "$ref": "#/components/schemas/SlideshowStyleContextV1" } }, "additionalProperties": false, "description": "Complete deterministic slideshow project, including slides, styles, asset bindings, output settings, and the pinned renderer runtime." }, "SlideshowRuntimeV1": { "type": "object", "required": [ "rendererVersion", "remotionVersion", "reactVersion", "platform", "entryPoint", "dependencyAllowlistVersion" ], "properties": { "rendererVersion": { "type": "string", "description": "a string at most 128 character(s) long", "title": "maxLength(128)", "minLength": 1, "maxLength": 128 }, "remotionVersion": { "type": "string", "description": "a string at most 128 character(s) long", "title": "maxLength(128)", "minLength": 1, "maxLength": 128 }, "reactVersion": { "type": "string", "description": "a string at most 128 character(s) long", "title": "maxLength(128)", "minLength": 1, "maxLength": 128 }, "platform": { "type": "string", "enum": [ "linux-arm64" ] }, "entryPoint": { "$ref": "#/components/schemas/SlideshowSourcePath" }, "dependencyAllowlistVersion": { "type": "string", "description": "a string at most 128 character(s) long", "title": "maxLength(128)", "minLength": 1, "maxLength": 128 } }, "additionalProperties": false }, "SlideshowOutputV1": { "type": "object", "required": [ "aspectRatio", "width", "height", "fps" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "4:5", "9:16", "1:1", "16:9" ] }, "width": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, "height": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, "fps": { "type": "number", "enum": [ 30 ] } }, "additionalProperties": false }, "SlideshowSlideV1": { "type": "object", "required": [ "id", "durationFrames", "posterFrame", "assetBindingIds", "textElements" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "durationFrames": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 18000", "title": "between(1, 18000)", "minimum": 1, "maximum": 18000 }, "posterFrame": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "assetBindingIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "an array of at most 128 item(s)", "title": "maxItems(128)", "maxItems": 128 }, "backgroundBindingId": { "$ref": "#/components/schemas/UUID" }, "backgroundPresentation": { "$ref": "#/components/schemas/SlideshowBackgroundPresentationV1" }, "textElements": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowTextElementV1" }, "description": "an array of at most 64 item(s)", "title": "maxItems(64)", "maxItems": 64 }, "embeddedText": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowEmbeddedTextV1" }, "description": "an array of at most 64 item(s)", "title": "maxItems(64)", "maxItems": 64 } }, "additionalProperties": false }, "SlideshowBackgroundPresentationV1": { "type": "object", "required": [ "fit", "focalPoint" ], "properties": { "fit": { "type": "string", "enum": [ "cover", "contain" ] }, "focalPoint": { "$ref": "#/components/schemas/SlideshowBackgroundFocalPointV1" }, "overlay": { "$ref": "#/components/schemas/SlideshowBackgroundOverlayV1" } }, "additionalProperties": false }, "SlideshowBackgroundFocalPointV1": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, "SlideshowBackgroundOverlayV1": { "type": "object", "required": [ "color", "opacity" ], "properties": { "color": { "type": "string", "description": "a string matching the pattern ^#[a-fA-F0-9]{6}$", "pattern": "^#[a-fA-F0-9]{6}$" }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, "SlideshowTextElementV1": { "type": "object", "required": [ "id", "role", "text", "position", "styleId", "overrides" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "role": { "type": "string", "enum": [ "hook", "heading", "body", "caption", "cta", "custom" ] }, "text": { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, "position": { "$ref": "#/components/schemas/SlideshowTextPositionV1" }, "styleId": { "type": "string", "description": "a string matching the pattern ^[A-Za-z][A-Za-z0-9._-]*$", "title": "maxLength(128)", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z][A-Za-z0-9._-]*$" }, "overrides": { "$ref": "#/components/schemas/SlideshowTextStyleOverrides" } }, "additionalProperties": false }, "SlideshowTextPositionV1": { "type": "object", "required": [ "x", "y", "width", "height", "rotation" ], "properties": { "x": { "type": "number", "description": "a number between -100000 and 100000", "title": "between(-100000, 100000)", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "description": "a number between -100000 and 100000", "title": "between(-100000, 100000)", "minimum": -100000, "maximum": 100000 }, "width": { "type": "number", "description": "a number between 1 and 100000", "title": "between(1, 100000)", "minimum": 1, "maximum": 100000 }, "height": { "type": "number", "description": "a number between 1 and 100000", "title": "between(1, 100000)", "minimum": 1, "maximum": 100000 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 } }, "additionalProperties": false }, "SlideshowTextStyleOverrides": { "type": "object", "required": [], "properties": { "fontFamily": { "type": "string", "enum": [ "TikTok Display", "Anton", "Arial", "Bebas Neue", "Bitcount", "Cinzel", "Della", "DynaPuff", "Eagle Lake", "Georgia", "Helvetica", "Inter", "Lexend", "Libre Baskerville", "Montserrat", "Noto Sans JP", "Noto Sans TC", "Open Sans", "Oswald", "Playwrite", "Poppins", "Public Sans", "Roboto", "Roboto Slab", "Rubik", "Russo One", "TikTok Sans", "Times New Roman" ] }, "fontWeight": { "$ref": "#/components/schemas/Int", "description": "a number between 100 and 900", "title": "between(100, 900)", "minimum": 100, "maximum": 900 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "lineHeight": { "type": "number", "description": "a number between 0.5 and 4", "title": "between(0.5, 4)", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "description": "a number between -32 and 96", "title": "between(-32, 96)", "minimum": -32, "maximum": 96 }, "fill": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "strokeColor": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "strokeWidth": { "type": "number", "description": "a number between 0 and 32", "title": "between(0, 32)", "minimum": 0, "maximum": 32 }, "shadowColor": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "shadowBlur": { "type": "number", "description": "a number between 0 and 128", "title": "between(0, 128)", "minimum": 0, "maximum": 128 }, "shadowOffsetX": { "type": "number", "description": "a number between -256 and 256", "title": "between(-256, 256)", "minimum": -256, "maximum": 256 }, "shadowOffsetY": { "type": "number", "description": "a number between -256 and 256", "title": "between(-256, 256)", "minimum": -256, "maximum": 256 }, "panelColor": { "type": "string", "description": "a string matching the pattern ^#[a-fA-F0-9]{6}$", "pattern": "^#[a-fA-F0-9]{6}$" }, "panelOpacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "padding": { "type": "number", "description": "a number between 0 and 256", "title": "between(0, 256)", "minimum": 0, "maximum": 256 }, "borderRadius": { "type": "number", "description": "a number between 0 and 256", "title": "between(0, 256)", "minimum": 0, "maximum": 256 }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "italic": { "type": "boolean" }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "maxWidth": { "type": "number", "description": "a number between 1 and 4096", "title": "between(1, 4096)", "minimum": 1, "maximum": 4096 } }, "additionalProperties": false }, "SlideshowEmbeddedTextV1": { "type": "object", "required": [ "role", "text" ], "properties": { "role": { "type": "string", "enum": [ "hook", "heading", "body", "caption", "cta", "custom" ] }, "text": { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 } }, "additionalProperties": false }, "SlideshowStylesV1": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$ref": "#/components/schemas/SlideshowTextStyleV1" } }, "SlideshowTextStyleV1": { "type": "object", "required": [ "preset" ], "properties": { "preset": { "type": "string", "enum": [ "white_outline", "muted_dark_panel", "white_panel", "soft_shadow", "black_panel", "plain_dark" ] }, "fontFamily": { "type": "string", "enum": [ "TikTok Display", "Anton", "Arial", "Bebas Neue", "Bitcount", "Cinzel", "Della", "DynaPuff", "Eagle Lake", "Georgia", "Helvetica", "Inter", "Lexend", "Libre Baskerville", "Montserrat", "Noto Sans JP", "Noto Sans TC", "Open Sans", "Oswald", "Playwrite", "Poppins", "Public Sans", "Roboto", "Roboto Slab", "Rubik", "Russo One", "TikTok Sans", "Times New Roman" ] }, "fontWeight": { "$ref": "#/components/schemas/Int", "description": "a number between 100 and 900", "title": "between(100, 900)", "minimum": 100, "maximum": 900 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "lineHeight": { "type": "number", "description": "a number between 0.5 and 4", "title": "between(0.5, 4)", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "description": "a number between -32 and 96", "title": "between(-32, 96)", "minimum": -32, "maximum": 96 }, "fill": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "strokeColor": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "strokeWidth": { "type": "number", "description": "a number between 0 and 32", "title": "between(0, 32)", "minimum": 0, "maximum": 32 }, "shadowColor": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "shadowBlur": { "type": "number", "description": "a number between 0 and 128", "title": "between(0, 128)", "minimum": 0, "maximum": 128 }, "shadowOffsetX": { "type": "number", "description": "a number between -256 and 256", "title": "between(-256, 256)", "minimum": -256, "maximum": 256 }, "shadowOffsetY": { "type": "number", "description": "a number between -256 and 256", "title": "between(-256, 256)", "minimum": -256, "maximum": 256 }, "panelColor": { "type": "string", "description": "a string matching the pattern ^#[a-fA-F0-9]{6}$", "pattern": "^#[a-fA-F0-9]{6}$" }, "panelOpacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "padding": { "type": "number", "description": "a number between 0 and 256", "title": "between(0, 256)", "minimum": 0, "maximum": 256 }, "borderRadius": { "type": "number", "description": "a number between 0 and 256", "title": "between(0, 256)", "minimum": 0, "maximum": 256 }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "italic": { "type": "boolean" }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "maxWidth": { "type": "number", "description": "a number between 1 and 4096", "title": "between(1, 4096)", "minimum": 1, "maximum": 4096 } }, "additionalProperties": false }, "SlideshowAssetBindingsV1": { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$ref": "#/components/schemas/SlideshowAssetBindingV1" } }, "SlideshowAssetBindingV1": { "type": "object", "required": [ "mediaAssetId", "sha256", "usage" ], "properties": { "mediaAssetId": { "$ref": "#/components/schemas/UUID" }, "sha256": { "$ref": "#/components/schemas/SlideshowSha256" }, "usage": { "type": "string", "enum": [ "background", "foreground", "texture", "logo", "custom" ] } }, "additionalProperties": false }, "SlideshowStyleContextV1": { "type": "object", "required": [ "renderTokens", "references" ], "properties": { "renderTokens": { "type": "object", "required": [], "properties": {}, "patternProperties": { "": { "anyOf": [ { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "maxLength": 512 }, { "type": "number", "description": "a finite number", "title": "finite" }, { "type": "boolean" } ] } }, "propertyNames": { "type": "string", "description": "a string matching the pattern ^[A-Za-z][A-Za-z0-9._-]*$", "title": "maxLength(128)", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z][A-Za-z0-9._-]*$" } }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowReferenceProvenanceV1" }, "description": "an array of at most 64 item(s)", "title": "maxItems(64)", "maxItems": 64 } }, "additionalProperties": false }, "SlideshowReferenceProvenanceV1": { "type": "object", "required": [ "source", "sourceId" ], "properties": { "source": { "type": "string", "enum": [ "team_asset", "team_slideshow", "pinterest", "unsplash", "image_pack", "shared_image_pack", "generated_image" ] }, "sourceId": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "minLength": 1, "maxLength": 512 }, "label": { "type": "string", "description": "a string at most 512 character(s) long", "title": "maxLength(512)", "maxLength": 512 }, "sha256": { "$ref": "#/components/schemas/SlideshowSha256" } }, "additionalProperties": false }, "ContentRenderJobResponse": { "type": "object", "required": [ "id", "contentItemId", "artifactRunId", "payloadId", "payloadRevision", "creativeHash", "rendererVersion", "status", "workflowId", "outputWidth", "outputHeight", "slideCount", "pixelCount", "outputManifest", "durationMs", "hostId", "errorClass", "errorCode", "diagnostics", "retryable", "createdAt", "startedAt", "completedAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "contentItemId": { "$ref": "#/components/schemas/UUID" }, "artifactRunId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "payloadId": { "$ref": "#/components/schemas/UUID" }, "payloadRevision": { "$ref": "#/components/schemas/Int" }, "creativeHash": { "type": "string" }, "rendererVersion": { "type": "string" }, "status": { "type": "string" }, "workflowId": { "type": "string" }, "outputWidth": { "$ref": "#/components/schemas/Int" }, "outputHeight": { "$ref": "#/components/schemas/Int" }, "slideCount": { "$ref": "#/components/schemas/Int" }, "pixelCount": { "$ref": "#/components/schemas/Int" }, "outputManifest": { "anyOf": [ { "type": "object", "required": [], "properties": {}, "additionalProperties": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ] }, "durationMs": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "hostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorClass": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, "CreateSlideshowBody": { "type": "object", "required": [ "project" ], "properties": { "title": { "type": "string", "description": "a string at most 500 character(s) long", "title": "maxLength(500)", "maxLength": 500 }, "project": { "type": "object", "required": [ "schemaVersion", "artifactKind", "runtime", "sourceFiles", "output", "slides", "styles", "assetBindings", "styleContext" ], "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "artifactKind": { "type": "string", "enum": [ "slideshow" ] }, "runtime": { "$ref": "#/components/schemas/SlideshowRuntimeV1" }, "sourceFiles": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowSourceFileV1" }, "description": "an array of at most 64 item(s)", "title": "maxItems(64)", "minItems": 1, "maxItems": 64 }, "output": { "$ref": "#/components/schemas/SlideshowOutputV1" }, "slides": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowSlideV1" }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 2, "maxItems": 20 }, "styles": { "$ref": "#/components/schemas/SlideshowStylesV1" }, "assetBindings": { "$ref": "#/components/schemas/SlideshowAssetBindingsV1" }, "styleContext": { "$ref": "#/components/schemas/SlideshowStyleContextV1" } }, "additionalProperties": false, "description": "Complete deterministic slideshow project, including slides, styles, asset bindings, output settings, and the pinned renderer runtime." }, "autoRender": { "type": "boolean", "description": "When true, queue a render immediately after creating the slideshow; defaults to false." } }, "additionalProperties": false }, "SlideshowListResponse": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowArtifactResponse" } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "SlideshowArtifactResponse": { "type": "object", "required": [ "contentItemId", "teamId", "sourceContentItemId", "title", "status", "payloadId", "revision", "creativeHash", "currentCreativeHash", "renderedCreativeHash", "renderFresh", "activeRun", "latestRun", "latestRenderJob", "project", "assetRefs", "links" ], "properties": { "contentItemId": { "$ref": "#/components/schemas/UUID" }, "teamId": { "$ref": "#/components/schemas/UUID" }, "sourceContentItemId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "payloadId": { "$ref": "#/components/schemas/UUID" }, "revision": { "$ref": "#/components/schemas/Int" }, "creativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currentCreativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "renderedCreativeHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "renderFresh": { "type": "boolean" }, "browserPreviewUrl": { "type": "string" }, "previewCreativeHash": { "type": "string" }, "activeRun": { "anyOf": [ { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "latestRun": { "anyOf": [ { "type": "object", "required": [ "id", "status", "errorCode", "diagnostics" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "diagnostics": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ], "description": "The most recent agent run whatever its outcome, so a failure is visible without having kept its run id." }, "latestRenderJob": { "anyOf": [ { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "status": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "project": { "anyOf": [ { "$ref": "#/components/schemas/SlideshowProjectV1" }, { "type": "null" } ] }, "assetRefs": { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, "links": { "type": "object", "required": [ "self", "revisions", "latestRenderJob" ], "properties": { "self": { "type": "string" }, "revisions": { "type": "string" }, "latestRenderJob": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "CreateSlideshowDraftBody": { "type": "object", "required": [ "draft" ], "properties": { "title": { "type": "string", "description": "a string at most 500 character(s) long", "title": "maxLength(500)", "maxLength": 500 }, "draft": { "type": "object", "required": [ "slides" ], "properties": { "slides": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowDraftSlideV1" }, "description": "Between two and twenty slides.", "title": "maxItems(20)", "minItems": 2, "maxItems": 20 }, "aspectRatio": { "type": "string", "enum": [ "4:5", "9:16", "1:1", "16:9" ], "description": "Output aspect ratio; defaults to 4:5." }, "captionPreset": { "type": "string", "enum": [ "white_outline", "muted_dark_panel", "white_panel", "soft_shadow", "black_panel", "plain_dark" ], "description": "Caption style preset applied across the deck; defaults to white_outline." } }, "additionalProperties": false, "description": "Minimal slideshow description. Only slide text is required - the pinned renderer runtime, source bundle, output size, styles, caption layout and identifiers are all filled in for you." }, "autoRender": { "type": "boolean", "description": "When true, queue a render immediately after creating the slideshow; defaults to false." } }, "additionalProperties": false }, "SlideshowDraftSlideV1": { "type": "object", "required": [], "properties": { "text": { "type": "string", "description": "Shorthand for a slide with a single caption.", "title": "maxLength(4000)", "maxLength": 4000 }, "captions": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowDraftCaptionV1" }, "description": "Ordered captions when a slide needs more than one.", "title": "maxItems(64)", "maxItems": 64 }, "media": { "type": "object", "required": [ "mediaAssetId", "sha256" ], "properties": { "mediaAssetId": { "$ref": "#/components/schemas/UUID" }, "sha256": { "$ref": "#/components/schemas/SlideshowSha256" } }, "additionalProperties": false, "description": "Optional team media asset to bind as this slide background." }, "durationFrames": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 18000", "title": "between(1, 18000)", "minimum": 1, "maximum": 18000 } }, "additionalProperties": false }, "SlideshowDraftCaptionV1": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Caption copy shown on the slide.", "title": "maxLength(4000)", "maxLength": 4000 }, "role": { "type": "string", "enum": [ "hook", "heading", "body", "caption", "cta", "custom" ], "description": "Editorial role of this caption; defaults to caption." } }, "additionalProperties": false }, "ApplySlideshowCommandsBody": { "type": "object", "required": [ "expectedRevision", "commands" ], "properties": { "expectedRevision": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, "commands": { "type": "array", "items": { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "slide.add" ] }, "index": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "durationFrames": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 18000", "title": "between(1, 18000)", "minimum": 1, "maximum": 18000 }, "captions": { "type": "array", "items": { "type": "object", "required": [ "role", "text" ], "properties": { "role": { "type": "string", "enum": [ "hook", "heading", "body", "caption", "cta", "custom" ] }, "text": { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, "position": { "type": "object", "required": [ "x", "y", "width", "height", "rotation" ], "properties": { "x": { "type": "number", "description": "a number between -100000 and 100000", "title": "between(-100000, 100000)", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "description": "a number between -100000 and 100000", "title": "between(-100000, 100000)", "minimum": -100000, "maximum": 100000 }, "width": { "type": "number", "description": "a number between 1 and 100000", "title": "between(1, 100000)", "minimum": 1, "maximum": 100000 }, "height": { "type": "number", "description": "a number between 1 and 100000", "title": "between(1, 100000)", "minimum": 1, "maximum": 100000 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 } }, "additionalProperties": false }, "styleId": { "type": "string", "description": "a string matching the pattern ^[A-Za-z][A-Za-z0-9._-]*$", "title": "maxLength(128)", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z][A-Za-z0-9._-]*$" }, "overrides": { "type": "object", "required": [], "properties": { "fontFamily": { "type": "string", "enum": [ "TikTok Display", "Anton", "Arial", "Bebas Neue", "Bitcount", "Cinzel", "Della", "DynaPuff", "Eagle Lake", "Georgia", "Helvetica", "Inter", "Lexend", "Libre Baskerville", "Montserrat", "Noto Sans JP", "Noto Sans TC", "Open Sans", "Oswald", "Playwrite", "Poppins", "Public Sans", "Roboto", "Roboto Slab", "Rubik", "Russo One", "TikTok Sans", "Times New Roman" ] }, "fontWeight": { "$ref": "#/components/schemas/Int", "description": "a number between 100 and 900", "title": "between(100, 900)", "minimum": 100, "maximum": 900 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "lineHeight": { "type": "number", "description": "a number between 0.5 and 4", "title": "between(0.5, 4)", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "description": "a number between -32 and 96", "title": "between(-32, 96)", "minimum": -32, "maximum": 96 }, "fill": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "strokeColor": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "strokeWidth": { "type": "number", "description": "a number between 0 and 32", "title": "between(0, 32)", "minimum": 0, "maximum": 32 }, "shadowColor": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "shadowBlur": { "type": "number", "description": "a number between 0 and 128", "title": "between(0, 128)", "minimum": 0, "maximum": 128 }, "shadowOffsetX": { "type": "number", "description": "a number between -256 and 256", "title": "between(-256, 256)", "minimum": -256, "maximum": 256 }, "shadowOffsetY": { "type": "number", "description": "a number between -256 and 256", "title": "between(-256, 256)", "minimum": -256, "maximum": 256 }, "panelColor": { "type": "string", "description": "a string matching the pattern ^#[a-fA-F0-9]{6}$", "pattern": "^#[a-fA-F0-9]{6}$" }, "panelOpacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "padding": { "type": "number", "description": "a number between 0 and 256", "title": "between(0, 256)", "minimum": 0, "maximum": 256 }, "borderRadius": { "type": "number", "description": "a number between 0 and 256", "title": "between(0, 256)", "minimum": 0, "maximum": 256 }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "italic": { "type": "boolean" }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "maxWidth": { "type": "number", "description": "a number between 1 and 4096", "title": "between(1, 4096)", "minimum": 1, "maximum": 4096 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 64 item(s)", "title": "maxItems(64)", "maxItems": 64 } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "slideId" ], "properties": { "type": { "type": "string", "enum": [ "slide.delete" ] }, "slideId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "slideId", "index" ], "properties": { "type": { "type": "string", "enum": [ "slide.move" ] }, "slideId": { "$ref": "#/components/schemas/UUID" }, "index": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "slideId", "caption" ], "properties": { "type": { "type": "string", "enum": [ "caption.add" ] }, "slideId": { "$ref": "#/components/schemas/UUID" }, "index": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "caption": { "type": "object", "required": [ "role", "text" ], "properties": { "role": { "type": "string", "enum": [ "hook", "heading", "body", "caption", "cta", "custom" ] }, "text": { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, "position": { "type": "object", "required": [ "x", "y", "width", "height", "rotation" ], "properties": { "x": { "type": "number", "description": "a number between -100000 and 100000", "title": "between(-100000, 100000)", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "description": "a number between -100000 and 100000", "title": "between(-100000, 100000)", "minimum": -100000, "maximum": 100000 }, "width": { "type": "number", "description": "a number between 1 and 100000", "title": "between(1, 100000)", "minimum": 1, "maximum": 100000 }, "height": { "type": "number", "description": "a number between 1 and 100000", "title": "between(1, 100000)", "minimum": 1, "maximum": 100000 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 } }, "additionalProperties": false }, "styleId": { "type": "string", "description": "a string matching the pattern ^[A-Za-z][A-Za-z0-9._-]*$", "title": "maxLength(128)", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z][A-Za-z0-9._-]*$" }, "overrides": { "type": "object", "required": [], "properties": { "fontFamily": { "type": "string", "enum": [ "TikTok Display", "Anton", "Arial", "Bebas Neue", "Bitcount", "Cinzel", "Della", "DynaPuff", "Eagle Lake", "Georgia", "Helvetica", "Inter", "Lexend", "Libre Baskerville", "Montserrat", "Noto Sans JP", "Noto Sans TC", "Open Sans", "Oswald", "Playwrite", "Poppins", "Public Sans", "Roboto", "Roboto Slab", "Rubik", "Russo One", "TikTok Sans", "Times New Roman" ] }, "fontWeight": { "$ref": "#/components/schemas/Int", "description": "a number between 100 and 900", "title": "between(100, 900)", "minimum": 100, "maximum": 900 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "lineHeight": { "type": "number", "description": "a number between 0.5 and 4", "title": "between(0.5, 4)", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "description": "a number between -32 and 96", "title": "between(-32, 96)", "minimum": -32, "maximum": 96 }, "fill": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "strokeColor": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "strokeWidth": { "type": "number", "description": "a number between 0 and 32", "title": "between(0, 32)", "minimum": 0, "maximum": 32 }, "shadowColor": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "shadowBlur": { "type": "number", "description": "a number between 0 and 128", "title": "between(0, 128)", "minimum": 0, "maximum": 128 }, "shadowOffsetX": { "type": "number", "description": "a number between -256 and 256", "title": "between(-256, 256)", "minimum": -256, "maximum": 256 }, "shadowOffsetY": { "type": "number", "description": "a number between -256 and 256", "title": "between(-256, 256)", "minimum": -256, "maximum": 256 }, "panelColor": { "type": "string", "description": "a string matching the pattern ^#[a-fA-F0-9]{6}$", "pattern": "^#[a-fA-F0-9]{6}$" }, "panelOpacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "padding": { "type": "number", "description": "a number between 0 and 256", "title": "between(0, 256)", "minimum": 0, "maximum": 256 }, "borderRadius": { "type": "number", "description": "a number between 0 and 256", "title": "between(0, 256)", "minimum": 0, "maximum": 256 }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "italic": { "type": "boolean" }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "maxWidth": { "type": "number", "description": "a number between 1 and 4096", "title": "between(1, 4096)", "minimum": 1, "maximum": 4096 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "slideId", "textElementId" ], "properties": { "type": { "type": "string", "enum": [ "caption.delete" ] }, "slideId": { "$ref": "#/components/schemas/UUID" }, "textElementId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "slideId", "textElementId", "index" ], "properties": { "type": { "type": "string", "enum": [ "caption.move" ] }, "slideId": { "$ref": "#/components/schemas/UUID" }, "textElementId": { "$ref": "#/components/schemas/UUID" }, "index": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "slideId", "textElementId" ], "properties": { "type": { "type": "string", "enum": [ "caption.edit" ] }, "slideId": { "$ref": "#/components/schemas/UUID" }, "textElementId": { "$ref": "#/components/schemas/UUID" }, "text": { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "maxLength": 4000 }, "role": { "type": "string", "enum": [ "hook", "heading", "body", "caption", "cta", "custom" ] }, "position": { "type": "object", "required": [ "x", "y", "width", "height", "rotation" ], "properties": { "x": { "type": "number", "description": "a number between -100000 and 100000", "title": "between(-100000, 100000)", "minimum": -100000, "maximum": 100000 }, "y": { "type": "number", "description": "a number between -100000 and 100000", "title": "between(-100000, 100000)", "minimum": -100000, "maximum": 100000 }, "width": { "type": "number", "description": "a number between 1 and 100000", "title": "between(1, 100000)", "minimum": 1, "maximum": 100000 }, "height": { "type": "number", "description": "a number between 1 and 100000", "title": "between(1, 100000)", "minimum": 1, "maximum": 100000 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 } }, "additionalProperties": false }, "styleId": { "type": "string", "description": "a string matching the pattern ^[A-Za-z][A-Za-z0-9._-]*$", "title": "maxLength(128)", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z][A-Za-z0-9._-]*$" }, "overrides": { "type": "object", "required": [], "properties": { "fontFamily": { "type": "string", "enum": [ "TikTok Display", "Anton", "Arial", "Bebas Neue", "Bitcount", "Cinzel", "Della", "DynaPuff", "Eagle Lake", "Georgia", "Helvetica", "Inter", "Lexend", "Libre Baskerville", "Montserrat", "Noto Sans JP", "Noto Sans TC", "Open Sans", "Oswald", "Playwrite", "Poppins", "Public Sans", "Roboto", "Roboto Slab", "Rubik", "Russo One", "TikTok Sans", "Times New Roman" ] }, "fontWeight": { "$ref": "#/components/schemas/Int", "description": "a number between 100 and 900", "title": "between(100, 900)", "minimum": 100, "maximum": 900 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "lineHeight": { "type": "number", "description": "a number between 0.5 and 4", "title": "between(0.5, 4)", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "description": "a number between -32 and 96", "title": "between(-32, 96)", "minimum": -32, "maximum": 96 }, "fill": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "strokeColor": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "strokeWidth": { "type": "number", "description": "a number between 0 and 32", "title": "between(0, 32)", "minimum": 0, "maximum": 32 }, "shadowColor": { "type": "string", "description": "a string at most 64 character(s) long", "title": "maxLength(64)", "minLength": 1, "maxLength": 64 }, "shadowBlur": { "type": "number", "description": "a number between 0 and 128", "title": "between(0, 128)", "minimum": 0, "maximum": 128 }, "shadowOffsetX": { "type": "number", "description": "a number between -256 and 256", "title": "between(-256, 256)", "minimum": -256, "maximum": 256 }, "shadowOffsetY": { "type": "number", "description": "a number between -256 and 256", "title": "between(-256, 256)", "minimum": -256, "maximum": 256 }, "panelColor": { "type": "string", "description": "a string matching the pattern ^#[a-fA-F0-9]{6}$", "pattern": "^#[a-fA-F0-9]{6}$" }, "panelOpacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "padding": { "type": "number", "description": "a number between 0 and 256", "title": "between(0, 256)", "minimum": 0, "maximum": 256 }, "borderRadius": { "type": "number", "description": "a number between 0 and 256", "title": "between(0, 256)", "minimum": 0, "maximum": 256 }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "italic": { "type": "boolean" }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "maxWidth": { "type": "number", "description": "a number between 1 and 4096", "title": "between(1, 4096)", "minimum": 1, "maximum": 4096 } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "slideId", "mediaAssetId" ], "properties": { "type": { "type": "string", "enum": [ "background.attach_media" ] }, "slideId": { "$ref": "#/components/schemas/UUID" }, "mediaAssetId": { "$ref": "#/components/schemas/UUID" }, "presentation": { "type": "object", "required": [ "fit", "focalPoint" ], "properties": { "fit": { "type": "string", "enum": [ "cover", "contain" ] }, "focalPoint": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, "overlay": { "type": "object", "required": [ "color", "opacity" ], "properties": { "color": { "type": "string", "description": "a string matching the pattern ^#[a-fA-F0-9]{6}$", "pattern": "^#[a-fA-F0-9]{6}$" }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "slideId" ], "properties": { "type": { "type": "string", "enum": [ "background.clear" ] }, "slideId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "required": [ "type", "imagePackId", "target" ], "properties": { "type": { "type": "string", "enum": [ "background.apply_image_pack" ] }, "imagePackId": { "type": "string", "description": "a string at most 128 character(s) long", "title": "maxLength(128)", "minLength": 1, "maxLength": 128 }, "selection": { "type": "string", "enum": [ "auto", "sequential" ] }, "target": { "type": "string", "enum": [ "automatic_slides" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "slideId", "instruction", "source" ], "properties": { "type": { "type": "string", "enum": [ "background.request" ] }, "slideId": { "$ref": "#/components/schemas/UUID" }, "instruction": { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "minLength": 1, "maxLength": 4000 }, "source": { "anyOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "search" ] }, "providers": { "type": "array", "items": { "type": "string", "enum": [ "pinterest", "unsplash" ] }, "description": "an array of at most 2 item(s)", "title": "maxItems(2)", "minItems": 1, "maxItems": 2 } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "renderMode" ], "properties": { "kind": { "type": "string", "enum": [ "generate" ] }, "renderMode": { "type": "string", "enum": [ "background", "complete_slide" ] } }, "additionalProperties": false } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "instruction", "targetSlideIds" ], "properties": { "type": { "type": "string", "enum": [ "component.generate" ] }, "instruction": { "type": "string", "description": "a string at most 4000 character(s) long", "title": "maxLength(4000)", "minLength": 1, "maxLength": 4000 }, "targetSlideIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 } }, "additionalProperties": false } ] } ] }, "description": "an array of at most 100 item(s)", "title": "maxItems(100)", "minItems": 1, "maxItems": 100 } }, "additionalProperties": false }, "SlideshowRevisionResponse": { "type": "object", "required": [ "contentItemId", "payloadId", "revision", "kind", "creativeHash", "reversesRevision", "artifactRunId", "actorType", "actorUserId", "commands" ], "properties": { "contentItemId": { "$ref": "#/components/schemas/UUID" }, "payloadId": { "$ref": "#/components/schemas/UUID" }, "revision": { "$ref": "#/components/schemas/Int" }, "kind": { "type": "string", "enum": [ "root", "edit", "undo", "generation", "regeneration" ] }, "creativeHash": { "type": "string" }, "reversesRevision": { "anyOf": [ { "$ref": "#/components/schemas/Int" }, { "type": "null" } ] }, "artifactRunId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "actorType": { "type": "string" }, "actorUserId": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "commands": { "anyOf": [ { "type": "array", "items": { "$id": "/schemas/unknown", "title": "unknown" } }, { "type": "null" } ], "description": "The accepted semantic command batch, when this revision came from commands rather than a whole-project save." } }, "additionalProperties": false }, "SaveSlideshowProjectBody": { "type": "object", "required": [ "expectedRevision", "project" ], "properties": { "expectedRevision": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, "project": { "$ref": "#/components/schemas/SlideshowProjectV1" } }, "additionalProperties": false }, "UndoSlideshowBody": { "type": "object", "required": [ "expectedRevision" ], "properties": { "expectedRevision": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "RedoSlideshowBody": { "type": "object", "required": [ "expectedRevision" ], "properties": { "expectedRevision": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "DuplicateSlideshowBody": { "type": "object", "required": [ "expectedRevision" ], "properties": { "expectedRevision": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, "title": { "type": "string", "description": "a string at most 500 character(s) long", "title": "maxLength(500)", "maxLength": 500 } }, "additionalProperties": false }, "RegenerateSlideshowSlideBody": { "type": "object", "required": [ "expectedRevision", "scope" ], "properties": { "expectedRevision": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, "scope": { "type": "string", "enum": [ "text", "image", "layout", "style", "all" ], "description": "Part of the target slide to regenerate: all content, text only, or imagery only." }, "instruction": { "type": "string", "description": "a string at most 500 character(s) long", "title": "maxLength(500)", "maxLength": 500 }, "imageSource": { "anyOf": [ { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "auto" ] }, "strategy": { "type": "string", "enum": [ "auto", "search", "generate" ] }, "searchProviders": { "type": "array", "items": { "type": "string", "enum": [ "pinterest", "unsplash" ] }, "description": "an array of at most 2 item(s)", "title": "maxItems(2)", "maxItems": 2 }, "generationRenderMode": { "type": "string", "enum": [ "background", "complete_slide" ] } }, "additionalProperties": false }, { "type": "object", "required": [ "mode", "mediaAssetId" ], "properties": { "mode": { "type": "string", "enum": [ "media_asset" ] }, "mediaAssetId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false }, { "type": "object", "required": [ "mode", "imagePackId" ], "properties": { "mode": { "type": "string", "enum": [ "image_pack" ] }, "imagePackId": { "type": "string", "description": "a string at most 128 character(s) long", "title": "maxLength(128)", "minLength": 1, "maxLength": 128 }, "selection": { "type": "string", "enum": [ "auto", "sequential" ] } }, "additionalProperties": false } ], "description": "Exact media acquisition strategy required for this slide regeneration." }, "applyImagePackToAutomaticSlides": { "type": "boolean", "description": "Apply the selected image pack to every non-manual slide in one durable run." }, "visualChecks": { "type": "boolean", "description": "When true, render visual checks for the agent to inspect and polish the regenerated slide. Defaults to false; an interactive browser preview is still available." }, "autoRender": { "type": "boolean", "description": "When true, export the slideshow after the regenerated slide commits. Defaults to false; regeneration leaves an editable draft." } }, "additionalProperties": false }, "RenderContentArtifactBody": { "type": "object", "required": [ "expectedRevision" ], "properties": { "expectedRevision": { "$ref": "#/components/schemas/Int", "description": "a positive number", "title": "positive", "exclusiveMinimum": 0 }, "profile": { "type": "string", "enum": [ "cheap", "expensive" ], "description": "Render quality and output profile. Omit to use the normal final-render profile." }, "slideIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 } }, "additionalProperties": false }, "SlideshowRevisionsResponse": { "type": "object", "required": [ "data", "total", "nextCursor", "prevCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SlideshowRevisionResponse" } }, "total": { "type": "number" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "GenerateMemeImageBody": { "type": "object", "required": [ "prompt", "aspectRatio" ], "properties": { "prompt": { "type": "string", "description": "a string at most 12000 character(s) long", "title": "maxLength(12000)", "minLength": 1, "maxLength": 12000 }, "styleTags": { "type": "array", "items": { "type": "string", "description": "a string at most 2000 character(s) long", "title": "maxLength(2000)", "minLength": 1, "maxLength": 2000 }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "maxItems": 20 }, "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ], "description": "Output proportions for the generated image and optional caption overlay." }, "imageModelId": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "minLength": 1, "maxLength": 200 }, "quality": { "type": "string", "enum": [ "standard", "detailed" ], "description": "Image generation quality preference. Omit to use the normal quality setting." }, "caption": { "type": "string", "description": "a string at most 2000 character(s) long", "title": "maxLength(2000)", "maxLength": 2000 }, "captions": { "type": "array", "items": { "type": "object", "required": [ "id", "text", "x", "y", "width", "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "text": { "type": "string", "description": "a string at most 2000 character(s) long", "title": "maxLength(2000)", "maxLength": 2000 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "maxItems": 20 } }, "additionalProperties": false }, "PromoteMemeTemplateBody": { "type": "object", "required": [ "assetId", "generationId" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false }, "PromoteMemeTemplateResponse": { "type": "object", "required": [ "assetId", "editorHref", "captions" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "editorHref": { "type": "string" }, "captions": { "type": "array", "items": { "type": "object", "required": [ "id", "text", "x", "y", "width", "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "text": { "type": "string", "description": "a string at most 2000 character(s) long", "title": "maxLength(2000)", "maxLength": 2000 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } } }, "additionalProperties": false }, "SearchBackgroundsBody": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "a string at most 650 character(s) long", "title": "maxLength(650)", "minLength": 1, "maxLength": 650 }, "providers": { "type": "array", "items": { "type": "string", "enum": [ "unsplash", "pinterest" ] }, "description": "an array of at most 2 item(s)", "title": "maxItems(2)", "minItems": 1, "maxItems": 2 }, "packId": { "type": "string", "description": "a string at most 128 character(s) long", "title": "maxLength(128)", "maxLength": 128 }, "runId": { "$ref": "#/components/schemas/UUID" }, "limit": { "$ref": "#/components/schemas/Int", "description": "a number between 1 and 20", "title": "between(1, 20)", "minimum": 1, "maximum": 20 } }, "additionalProperties": false }, "SearchBackgroundsResponse": { "type": "object", "required": [ "data", "fallback", "diagnostics", "costDecimillicents" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "source", "sourceId", "url" ], "properties": { "source": { "type": "string", "enum": [ "unsplash", "pinterest", "library" ] }, "sourceId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "downloadLocation": { "type": "string" }, "photographerName": { "type": "string" }, "photographerUrl": { "type": "string" }, "searchProvider": { "type": "string", "enum": [ "dataforseo" ] }, "mediaAssetId": { "$ref": "#/components/schemas/UUID" }, "sha256": { "type": "string" } }, "additionalProperties": false } }, "fallback": { "type": "boolean" }, "diagnostics": { "type": "array", "items": { "type": "string" } }, "costDecimillicents": { "type": "number" } }, "additionalProperties": false }, "SelectBackgroundBody": { "type": "object", "required": [ "source", "downloadLocation" ], "properties": { "source": { "type": "string", "enum": [ "unsplash" ], "description": "Provider whose download attribution is being recorded. Currently Unsplash." }, "downloadLocation": { "type": "string", "description": "a string at most 2048 character(s) long", "title": "maxLength(2048)", "maxLength": 2048 } }, "additionalProperties": false }, "SelectBackgroundResponse": { "type": "object", "required": [ "tracked" ], "properties": { "tracked": { "type": "boolean" } }, "additionalProperties": false }, "MediaTemplatePreviewResponse": { "type": "object", "required": [ "assetId", "url", "sha256", "assetTypeData" ], "properties": { "assetId": { "$ref": "#/components/schemas/UUID" }, "url": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assetTypeData": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "type", "width", "height", "format" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "format": { "type": "string" }, "colorSpace": { "type": "string" }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "video" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "duration": { "type": "number" }, "codec": { "type": "string" }, "bitrate": { "type": "number" }, "fps": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "duration", "codec" ], "properties": { "type": { "type": "string", "enum": [ "audio" ] }, "duration": { "type": "number" }, "sampleRate": { "type": "number" }, "channels": { "type": "number" }, "codec": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "width", "height", "frameCount" ], "properties": { "type": { "type": "string", "enum": [ "gif" ] }, "width": { "type": "number" }, "height": { "type": "number" }, "frameCount": { "type": "number" }, "duration": { "type": "number" }, "aspectRatio": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "type", "format" ], "properties": { "type": { "type": "string", "enum": [ "document" ] }, "pageCount": { "type": "number" }, "format": { "type": "string" } }, "additionalProperties": false } ] }, { "anyOf": [ { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "chromaKey", "analysisVersion", "confidence", "chromaKeyProfiles", "subjectAnalysis", "aspectRatioProfiles", "captioning", "audio", "composition" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "green_screen_template" ] }, "chromaKey": { "type": "object", "required": [ "keyColor", "ffmpegSimilarity", "ffmpegBlend", "spillRisk" ], "properties": { "keyColor": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}$", "pattern": "^#[0-9a-fA-F]{6}$" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" }, "spillRisk": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "additionalProperties": false }, "analysisVersion": { "type": "number" }, "confidence": { "type": "number" }, "chromaKeyProfiles": { "type": "object", "required": [ "baseline", "fallback" ], "properties": { "baseline": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "fallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false }, "confidence": { "type": "number" }, "strongFallback": { "type": "object", "required": [ "similarity", "blend" ], "properties": { "similarity": { "type": "number" }, "blend": { "type": "number" }, "despillMix": { "type": "number" }, "despillExpand": { "type": "number" }, "confidence": { "type": "number" }, "ffmpegSimilarity": { "type": "number" }, "ffmpegBlend": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "subjectAnalysis": { "type": "object", "required": [ "sampleCount", "sampleTimestampsSeconds", "representativeBounds", "subjectHeightFraction", "subjectWidthFraction", "centerXFraction", "bottomYFraction", "cropRisk", "faceRegion", "confidence" ], "properties": { "sampleCount": { "type": "number" }, "sampleTimestampsSeconds": { "type": "array", "items": { "type": "number" } }, "representativeBounds": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "defaultSubjectBounds": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "subjectHeightFraction": { "type": "number" }, "subjectWidthFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "bottomYFraction": { "type": "number" }, "cropRisk": { "type": "object", "required": [ "top", "bottom", "left", "right" ], "properties": { "top": { "type": "number" }, "bottom": { "type": "number" }, "left": { "type": "number" }, "right": { "type": "number" } }, "additionalProperties": false }, "defaultFaceRegion": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRange": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "motionRangeDelta": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "additionalProperties": false }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegion": { "anyOf": [ { "type": "object", "required": [ "left", "top", "right", "bottom", "widthFraction", "heightFraction", "centerXFraction", "centerYFraction", "bottomYFraction" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" }, "widthFraction": { "type": "number" }, "heightFraction": { "type": "number" }, "centerXFraction": { "type": "number" }, "centerYFraction": { "type": "number" }, "bottomYFraction": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "confidence": { "type": "number" } }, "additionalProperties": false }, "aspectRatioProfiles": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "aspectRatio", "targetForegroundHeightFraction", "minForegroundHeightFraction", "maxForegroundHeightFraction", "targetCenterX", "targetBottomY", "maxCropTopFraction", "maxCropBottomFraction", "maxCropLeftFraction", "maxCropRightFraction", "preferredCaptionZones", "forbiddenCaptionZones" ], "properties": { "aspectRatio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5" ] }, "targetForegroundHeightFraction": { "type": "number" }, "minForegroundHeightFraction": { "type": "number" }, "maxForegroundHeightFraction": { "type": "number" }, "targetCenterX": { "type": "number" }, "targetBottomY": { "type": "number" }, "maxCropTopFraction": { "type": "number" }, "maxCropBottomFraction": { "type": "number" }, "maxCropLeftFraction": { "type": "number" }, "maxCropRightFraction": { "type": "number" }, "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "captioning": { "type": "object", "required": [ "preferredCaptionZones", "forbiddenCaptionZones", "subjectBoundsByAspectRatio", "faceRegionByAspectRatio", "captionSafeBandsByAspectRatio", "preferredZonesByAspectRatio", "forbiddenZonesByAspectRatio" ], "properties": { "preferredCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbiddenCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "subjectBoundsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "faceRegionByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "left", "top", "right", "bottom" ], "properties": { "left": { "type": "number" }, "top": { "type": "number" }, "right": { "type": "number" }, "bottom": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "16:9": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "1:1": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } }, "4:5": { "type": "array", "items": { "type": "object", "required": [ "xMin", "xMax", "yMin", "yMax" ], "properties": { "zone": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] }, "xMin": { "type": "number" }, "xMax": { "type": "number" }, "yMin": { "type": "number" }, "yMax": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false }, "preferredZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "forbiddenZonesByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "16:9": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "1:1": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "4:5": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "audio": { "type": "object", "required": [ "hasAudio", "likelyHasMusic", "likelyHasSpeech", "needsMusic" ], "properties": { "hasAudio": { "type": "boolean" }, "likelyHasMusic": { "type": "boolean" }, "likelyHasSpeech": { "type": "boolean" }, "needsMusic": { "type": "boolean" } }, "additionalProperties": false }, "composition": { "type": "object", "required": [ "safeCaptionZones", "captionSafeBandsByAspectRatio", "recommendedBackgroundTags", "recommendedMusicTags", "recommendedSoundEffectTags" ], "properties": { "safeCaptionZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "captionSafeBandsByAspectRatio": { "type": "object", "required": [], "properties": { "9:16": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "16:9": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "1:1": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, "4:5": { "type": "object", "required": [ "preferred", "forbidden" ], "properties": { "preferred": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } }, "forbidden": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false } }, "additionalProperties": false }, "recommendedBackgroundTags": { "type": "array", "items": { "type": "string" } }, "recommendedMusicTags": { "type": "array", "items": { "type": "string" } }, "recommendedSoundEffectTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "aspectRatioCategory" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "background" ] }, "meme": { "type": "object", "required": [ "sourceTemplateId", "sourceUrl", "captionBoxCount" ], "properties": { "sourceTemplateId": { "type": "string" }, "sourceUrl": { "type": "string" }, "captionBoxCount": { "$ref": "#/components/schemas/Int", "description": "a non-negative number", "title": "nonNegative", "minimum": 0 }, "templatePageUrl": { "type": "string" }, "captionZones": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "x", "y", "width", "height", "style" ], "properties": { "key": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "description": "a string at most 200 character(s) long", "title": "maxLength(200)", "maxLength": 200 }, "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "rotation": { "type": "number", "description": "a number between -360 and 360", "title": "between(-360, 360)", "minimum": -360, "maximum": 360 }, "style": { "type": "object", "required": [ "fontFamily", "fontSize", "fill", "stroke", "strokeWidth", "align", "bold", "uppercase" ], "properties": { "fontFamily": { "type": "string", "description": "a string at most 100 character(s) long", "title": "maxLength(100)", "minLength": 1, "maxLength": 100 }, "fontSize": { "type": "number", "description": "a number between 6 and 512", "title": "between(6, 512)", "minimum": 6, "maximum": 512 }, "fill": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "stroke": { "type": "string", "description": "a string matching the pattern ^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$", "pattern": "^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$" }, "strokeWidth": { "type": "number", "description": "a number between 0 and 20", "title": "between(0, 20)", "minimum": 0, "maximum": 20 }, "align": { "type": "string", "enum": [ "left", "center", "right" ], "description": "Horizontal alignment of text inside its caption zone." }, "bold": { "type": "boolean", "description": "Render the caption in bold." }, "uppercase": { "type": "boolean", "description": "Display the caption in uppercase without changing its saved text." }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ], "description": "Vertical alignment inside the caption zone. Omit to centre the text." }, "italic": { "type": "boolean", "description": "Use italic text. Omit to use normal text." }, "shadow": { "type": "boolean", "description": "Add a text shadow for contrast. Omit to use the saved template style." }, "opacity": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "an array of at most 20 item(s)", "title": "maxItems(20)", "minItems": 1, "maxItems": 20 }, "layout": { "type": "object", "required": [ "source", "sourcePageUrl", "capturedAt", "canvasWidth", "canvasHeight", "imageBounds" ], "properties": { "source": { "type": "string", "enum": [ "imgflip_official", "official_generator_default", "ai_generated" ] }, "sourcePageUrl": { "type": "string" }, "capturedAt": { "type": "string" }, "canvasWidth": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "canvasHeight": { "type": "number", "description": "a number between 1 and 8192", "title": "between(1, 8192)", "minimum": 1, "maximum": 8192 }, "imageBounds": { "type": "object", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "description": "a number between 0 and 1", "title": "between(0, 1)", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 }, "height": { "type": "number", "description": "a number less than or equal to 1", "title": "lessThanOrEqualTo(1)", "exclusiveMinimum": 0, "maximum": 1 } }, "additionalProperties": false }, "sourceApiUrl": { "type": "string" }, "generatorScriptUrl": { "type": "string" }, "modelId": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/UUID" } }, "additionalProperties": false } }, "additionalProperties": false }, "aspectRatioCategory": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "other" ] }, "dominantColors": { "type": "array", "items": { "type": "string" } }, "isLoopable": { "type": "boolean" }, "textSafeZones": { "type": "array", "items": { "type": "string", "enum": [ "top", "middle", "bottom", "left", "right" ] } } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "mood", "energyLevel" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "music" ] }, "mood": { "type": "array", "items": { "type": "string" } }, "energyLevel": { "type": "string", "enum": [ "low", "medium", "high", "variable" ] }, "tempo": { "type": "string", "enum": [ "slow", "medium", "fast", "variable" ] }, "hasVocals": { "type": "boolean" }, "isLoopable": { "type": "boolean" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "title", "localPath", "qualityScore", "probe", "source", "systemTemplateLibrary", "provenance", "kind", "effectCategory", "intensity", "timingUse" ], "properties": { "visualEnrichment": { "$ref": "#/components/schemas/SeedVisualEnrichment" }, "visualEnrichmentFailure": { "$ref": "#/components/schemas/SeedVisualEnrichmentFailure" }, "sourceAttribution": { "type": "object", "required": [ "provider", "sourceUrl" ], "properties": { "provider": { "type": "string" }, "sourceUrl": { "type": "string" }, "creator": { "type": "string" } }, "additionalProperties": false }, "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "localPath": { "type": "string" }, "thumbnailPath": { "type": "string" }, "qualityScore": { "type": "number" }, "probe": { "type": "object", "required": [ "sizeBytes", "mimeType", "hasVideo", "hasAudio" ], "properties": { "durationSeconds": { "type": "number" }, "sizeBytes": { "type": "number" }, "mimeType": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "hasVideo": { "type": "boolean" }, "hasAudio": { "type": "boolean" }, "videoCodec": { "type": "string" }, "audioCodec": { "type": "string" }, "bitrate": { "type": "number" } }, "additionalProperties": false }, "source": { "type": "string", "enum": [ "seed_catalog" ] }, "systemTemplateLibrary": { "type": "boolean" }, "provenance": { "type": "object", "required": [ "sourceTags" ], "properties": { "sourceTags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "sound_effect" ] }, "effectCategory": { "type": "string" }, "intensity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "timingUse": { "type": "string", "enum": [ "intro", "impact", "reaction", "transition", "outro" ] } }, "additionalProperties": false } ] } ] }, { "type": "null" } ] } }, "additionalProperties": false } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key" } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Organizations", "description": "Organizations are the billing and membership boundary. List them to discover organization ids, then create or rename organizations as workspaces grow. Organization deletion, invitations, members, and API-key management stay in the web app." }, { "name": "Teams", "description": "Teams partition an organization into workspaces that own posts, connected social accounts, and media. Most other endpoints are scoped by teamId, so list teams first to find the id you need. Create, update, and delete are permission-gated (create_teams, manage_organization, delete_teams), and deleting the last remaining workspace in an organization returns 409." }, { "name": "Social accounts", "description": "The provider accounts (X, LinkedIn, Instagram, and the rest) connected to a team. List them to find the socialAccountIds you pass when scheduling or publishing a post." }, { "name": "Posts", "description": "Draft, schedule, and publish social posts across your connected accounts. Publishing fans a single post out to one or more accounts and returns a per-account result, so you can see exactly what went live where and retry only the accounts that failed." }, { "name": "Scheduling slots", "description": "Configure the weekly posting-time grid behind next-slot scheduling. List the effective slots for a team, create or update custom slots, delete slots you no longer use, and ask the API for the next available occupied-aware slot before scheduling a post." }, { "name": "Analytics", "description": "Read performance for individual posts and for whole accounts. Live account reads pull fresh numbers from the providers and spend organization credits, so check your credit balance before large pulls." }, { "name": "Assets", "description": "The media library behind posts: upload images and video (URL, base64, or presigned upload for large files), then list, search, and organize assets. Semantic search is a paid operation; uploads trigger background thumbnailing and AI enrichment." }, { "name": "Agent", "description": "Bootstrap context for agent clients: the authenticated user, their organizations and teams, and sensible defaults to use when ids are not specified." }, { "name": "Billing", "description": "Credit balance, usage history, and top-ups for an organization. Paid operations reserve credits up front and finalize after completion, so the balance reflects holds as well as settled spend." }, { "name": "Media generation", "description": "Generate images and video from a prompt. Browse the model catalog, preview the credit cost with an estimate, then create a generation: it reserves credits up front and runs asynchronously, so poll it until the media is ready. Generations land in your media library as assets." }, { "name": "Agent schedules" }, { "name": "Brands", "description": "Brand profiles capture a team's voice, colors, and topics. Attach one to steer AI content generation so drafts stay on brand." }, { "name": "Folders", "description": "Hierarchical folders for organizing media-library assets within a team. Create, rename, and move operations only reshuffle references, but deleting a folder with mode=delete_contents soft-deletes every asset in its subtree (mode=move_to_parent reparents them instead)." }, { "name": "Media creation" }, { "name": "Personas" }, { "name": "Post notes" }, { "name": "Shortlinks" }, { "name": "Slideshows" }, { "name": "Sources", "description": "Registered content sources (URLs, uploads, and feeds) that ingestion pulls from to build your content library. Register a source, then reingest it or edit its extraction as the underlying content changes." }, { "name": "Support" }, { "name": "Tags" }, { "name": "Tasks" }, { "name": "Workflow statuses" } ], "servers": [ { "url": "https://api.octospark.ai", "description": "Octospark Production API" } ], "x-ddd": { "boundedContexts": [ { "name": "IdentityAccess", "owns": [ "Sign up/sign in", "Session token principal" ] }, { "name": "Collaboration", "owns": [ "Organizations", "Teams", "Invitations", "Membership" ] } ], "closedInvariants": [ { "id": "INV-AUTH-001", "rule": "Password must be at least 8 characters." }, { "id": "INV-AUTH-002", "rule": "Forgot-password responses are account-enumeration safe." }, { "id": "INV-ORG-001", "rule": "Organization members are the only actors allowed to manage resources in that organization." }, { "id": "INV-INV-001", "rule": "Invitations can be accepted only when status is pending, not expired, and email matches authenticated principal." }, { "id": "INV-INV-002", "rule": "Invitation list visibility is scoped to invitations whose email matches the authenticated principal." }, { "id": "INV-ARCH-001", "rule": "Domain mutations are accepted only via API/application services; direct UI-to-DB writes are forbidden." } ] } }