{ "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" } } } }, "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" } } } }, "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" } } } }, "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", "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" } ] }, "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" } } } }, "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", "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" } ] }, "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" } } } }, "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", "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" } ] }, "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" } } } }, "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" ] } }, "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" } } } }, "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } } } }, "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } } } }, "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", "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": "provider", "in": "query", "schema": { "type": "string", "enum": [ "x", "tiktok", "instagram", "facebook", "youtube", "linkedin", "threads" ], "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[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", "title", "status", "text", "assetIds", "assetTags", "userTags", "contentPayloadId", "latestScheduledPost", "scheduledDestinationAccountIds", "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" ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "idea", "proposed_render", "draft", "approved", "rejected", "archived", "deleted" ], "description": "Editorial status of a post: idea, proposed_render, draft, approved, rejected, archived, or deleted.", "examples": [ "draft", "approved" ] }, "text": { "type": "string" }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "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." }, "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } }, "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" } } } }, "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", "title", "status", "text", "assetIds", "assetTags", "userTags", "contentPayloadId", "latestScheduledPost", "scheduledDestinationAccountIds", "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" ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "idea", "proposed_render", "draft", "approved", "rejected", "archived", "deleted" ], "description": "Editorial status of a post: idea, proposed_render, draft, approved, rejected, archived, or deleted.", "examples": [ "draft", "approved" ] }, "text": { "type": "string" }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "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." }, "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } }, "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" } } } }, "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 from plain text or a structured postInput, with optional assetIds for media and postPublishActions (first comment, engagement trigger, repost). Nothing is published by this call: the post stays in draft until you call schedulePost or postNow with target social accounts.", "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." } }, "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", "title", "status", "text", "assetIds", "assetTags", "userTags", "contentPayloadId", "latestScheduledPost", "scheduledDestinationAccountIds", "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" ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "idea", "proposed_render", "draft", "approved", "rejected", "archived", "deleted" ], "description": "Editorial status of a post: idea, proposed_render, draft, approved, rejected, archived, or deleted.", "examples": [ "draft", "approved" ] }, "text": { "type": "string" }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "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." }, "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } }, "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" } } } }, "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", "title", "status", "text", "assetIds", "assetTags", "userTags", "contentPayloadId", "latestScheduledPost", "scheduledDestinationAccountIds", "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" ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "idea", "proposed_render", "draft", "approved", "rejected", "archived", "deleted" ], "description": "Editorial status of a post: idea, proposed_render, draft, approved, rejected, archived, or deleted.", "examples": [ "draft", "approved" ] }, "text": { "type": "string" }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "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." }, "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } }, "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" } } } }, "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 draft post's text or structured postInput, attached assetIds, or postPublishActions (first comment, engagement trigger, repost). Intended for drafts: to edit a scheduled post, call movePostToDraft first, make the changes, then reschedule.", "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." } }, "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } } } }, "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } }, "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" } } } }, "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 }, "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." } }, "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." } }, "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." }, "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } }, "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" } } } }, "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 }, "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." } }, "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." } }, "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." }, "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", "title", "status", "text", "assetIds", "assetTags", "userTags", "contentPayloadId", "latestScheduledPost", "scheduledDestinationAccountIds", "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" ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "idea", "proposed_render", "draft", "approved", "rejected", "archived", "deleted" ], "description": "Editorial status of a post: idea, proposed_render, draft, approved, rejected, archived, or deleted.", "examples": [ "draft", "approved" ] }, "text": { "type": "string" }, "assetIds": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" } }, "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." }, "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" ], "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } } } }, "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." } ], "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } ] } }, "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" } } } }, "429": { "description": "TooManyRequests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequests" } } } }, "500": { "description": "InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "description": "Read live account-level analytics (followers, posts, views) for each of the team's connected social accounts by calling the providers directly. Some providers (like X) charge credits for reads, so those accounts reserve organization credits first and an empty balance fails with 402. For a free, stored team-wide rollup instead, use getAnalyticsAggregates.", "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})" }, { "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\"}}'" }, { "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" ], "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" } } } }, "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } } } }, "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 across the accounts it was published to. 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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } } } }, "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}/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", "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" }, "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": { "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", "enum": [ "#00ff00" ] }, "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": { "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" ] }, "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": { "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": { "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" } ] }, "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" } } } }, "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. 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", "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" }, "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": { "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", "enum": [ "#00ff00" ] }, "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": { "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" ] }, "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": { "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": { "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" } ] }, "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" } } } }, "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" }, "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", "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" }, "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": { "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", "enum": [ "#00ff00" ] }, "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": { "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" ] }, "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": { "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": { "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" } ] }, "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" } } } }, "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" } } } }, "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", "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" }, "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": { "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", "enum": [ "#00ff00" ] }, "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": { "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" ] }, "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": { "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": { "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" } ] }, "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" } } } }, "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/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": [ "mode", "total", "data", "costResult", "embeddingStatus" ], "properties": { "mode": { "type": "string", "enum": [ "metadata", "semantic", "hybrid" ] }, "total": { "type": "number" }, "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", "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" }, "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": { "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", "enum": [ "#00ff00" ] }, "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": { "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" ] }, "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": { "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": { "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" } ] }, "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 } }, "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" } } } }, "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 over the team media library, 1 to 512 characters.", "title": "maxLength(512)", "minLength": 1, "examples": [ "green screen clip of someone pointing upward" ], "maxLength": 512 }, "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 50; defaults to 10.", "title": "lessThanOrEqualTo(50)", "minimum": 1, "default": 10, "examples": [ 10 ], "maximum": 50 }, "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", "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" }, "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": { "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", "enum": [ "#00ff00" ] }, "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": { "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" ] }, "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": { "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": { "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" } ] }, "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" } } } }, "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" } } } }, "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", "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" }, "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": { "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", "enum": [ "#00ff00" ] }, "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": { "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" ] }, "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": { "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": { "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" } ] }, "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" } } } }, "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", "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" }, "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": { "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", "enum": [ "#00ff00" ] }, "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": { "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" ] }, "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": { "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": { "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" } ] }, "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" } } } }, "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", "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" }, "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": { "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", "enum": [ "#00ff00" ] }, "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": { "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" ] }, "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": { "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": { "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" } ] }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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 100000 ($0.01), max 5000000000 ($500).", "title": "lessThanOrEqualTo(5000000000)", "minimum": 100000, "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", "openrouter", "fal" ], "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" ], "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", "openrouter", "fal" ] }, "modelOwnerProviderCode": { "type": "string", "enum": [ "google", "openai", "bytedance", "kuaishou", "alibaba", "openrouter", "fal" ] }, "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" ] } }, "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" ] }, "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" ] } }, "resolutions": { "type": "array", "items": { "type": "string", "enum": [ "720p", "1080p" ] } }, "durationsSeconds": { "type": "array", "items": { "type": "number" } }, "referenceImages": { "type": "object", "required": [ "arity" ], "properties": { "arity": { "type": "string", "enum": [ "none", "single", "multi" ] }, "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" } }, "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" } } } }, "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" ], "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", "openrouter", "fal" ] }, "modelOwnerProviderCode": { "type": "string", "enum": [ "google", "openai", "bytedance", "kuaishou", "alibaba", "openrouter", "fal" ] }, "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" ] } }, "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" ] }, "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" ] } }, "resolutions": { "type": "array", "items": { "type": "string", "enum": [ "720p", "1080p" ] } }, "durationsSeconds": { "type": "array", "items": { "type": "number" } }, "referenceImages": { "type": "object", "required": [ "arity" ], "properties": { "arity": { "type": "string", "enum": [ "none", "single", "multi" ] }, "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" } }, "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" } } } }, "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" } } } }, "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" ], "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" ] }, "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" ] }, "resolution": { "type": "string", "enum": [ "720p", "1080p" ] }, "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" ] }, "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" } } } }, "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" ] }, "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" } } } }, "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" ], "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" ] }, "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" ] }, "resolution": { "type": "string", "enum": [ "720p", "1080p" ] }, "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" ] }, "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" } } } }, "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" ] }, "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" } } } }, "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/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", "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" } ] }, "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" } } } }, "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", "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" } ] }, "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" } } } }, "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." }, "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", "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" } ] }, "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" } } } }, "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", "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" } ] }, "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" } } } }, "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." }, "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" } } } }, "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", "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" } ] }, "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" } } } }, "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}/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" } } } }, "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" } } } }, "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" } } } }, "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" } ] } } } }, "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}/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" } } } }, "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" } } } }, "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" } } } }, "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}/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" ], "description": "Social platform identifier: x, tiktok, instagram, facebook, youtube, linkedin, or threads.", "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" } } } }, "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" } } } }, "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", "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" }, "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" } } } }, "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. Filter by status or source type to find pending, failed, or completed extractions.", "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", "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" }, "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" } } } }, "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", "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" }, "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" } } } }, "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" } } } }, "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" } } } }, "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", "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" }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } }, "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" }, "_tag": { "type": "string", "enum": [ "Conflict" ] } }, "additionalProperties": false }, "TooManyRequests": { "type": "object", "required": [ "message", "_tag" ], "properties": { "message": { "type": "string" }, "_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}$" }, "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 }, "Int": { "type": "integer", "description": "an integer", "title": "int" } }, "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": "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": "Shortlinks" }, { "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": "Tags" } ], "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." } ] } }