{ "openapi": "3.1.0", "info": { "title": "Siren API", "version": "1.0.0", "description": "Siren public API. One brief becomes on-brand images, video, and posts.\n\n**Base URL:** `https://api.mysiren.ai`\n\n**Versioning:** URL path. Current surface is `/api/v1/`. Breaking changes\nship as `/api/v2/`. Additive fields on v1 responses are not breaking.\n\n**Deprecation:** a v1 operation that will go away is marked `deprecated: true`\nand the live response carries `Deprecation: true` plus a `Sunset` HTTP-date\nat least 90 days out. Agents should stop calling a sunset operation before\nthat date.\n\n**Auth:** `Authorization: Bearer sk_live_\u2026` or `sk_test_\u2026` (Pro+).\nMint keys in the dashboard under Developer. First onboarding post is free;\nAPI credits follow the workspace plan.\n\n**Errors:** JSON object `{ \"code\": string, \"message\": string, \"detail\"?: any }`.\nFastAPI validation may also send `{ \"detail\": \u2026 }`. Treat a string `detail`\nas the message and use `code` when present. `429` includes `Retry-After`\nand RateLimit-* headers.\n\n**Rate limits:** every response includes IETF `RateLimit-Limit` /\n`RateLimit-Remaining` / `RateLimit-Reset` and legacy `X-RateLimit-*`.\nHonor `Retry-After` on 429.\n\n**Docs:** https://mysiren.ai/api \u00b7 https://mysiren.ai/docs.txt \u00b7\nhttps://mysiren.ai/llms.txt \u00b7 MCP at https://mcp.mysiren.ai/mcp\n", "contact": { "name": "Siren Ai, Inc.", "url": "https://mysiren.ai", "email": "support@mysiren.ai" } }, "servers": [ { "url": "https://api.mysiren.ai", "description": "Production" } ], "paths": { "/api/v1/health": { "get": { "tags": [ "health" ], "summary": "Health", "description": "Reports per-dep status. HTTP 503 if any critical dep is down.", "operationId": "health_api_v1_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "title": "Response Health Api V1 Health Get" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/programmatic/brand-assets/screens": { "get": { "tags": [ "programmatic" ], "summary": "Programmatic List Screens", "operationId": "programmatic_list_screens_api_v1_programmatic_brand_assets_screens_get", "parameters": [ { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Programmatic List Screens Api V1 Programmatic Brand Assets Screens Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Programmatic List Screens. Siren public API on /api/v1/. Auth is Bearer sk_live_ or sk_test_. See https://mysiren.ai/api and https://mysiren.ai/openapi.json." }, "post": { "tags": [ "programmatic" ], "summary": "Programmatic Upload Screen", "description": "Ingest a product screenshot from image_url (https) or image_base64.\nStores on R2 and tags name / type / device / theme for the reasoner.", "operationId": "programmatic_upload_screen_api_v1_programmatic_brand_assets_screens_post", "parameters": [ { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgrammaticScreenIn" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Programmatic Upload Screen Api V1 Programmatic Brand Assets Screens Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/programmatic/brand-assets/screens/{screen_id}": { "patch": { "tags": [ "programmatic" ], "summary": "Programmatic Patch Screen", "operationId": "programmatic_patch_screen_api_v1_programmatic_brand_assets_screens__screen_id__patch", "parameters": [ { "name": "screen_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Screen Id" } }, { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Programmatic Patch Screen Api V1 Programmatic Brand Assets Screens Screen Id Patch" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Programmatic Patch Screen. Siren public API on /api/v1/. Auth is Bearer sk_live_ or sk_test_. See https://mysiren.ai/api and https://mysiren.ai/openapi.json." }, "delete": { "tags": [ "programmatic" ], "summary": "Programmatic Delete Screen", "operationId": "programmatic_delete_screen_api_v1_programmatic_brand_assets_screens__screen_id__delete", "parameters": [ { "name": "screen_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Screen Id" } }, { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Programmatic Delete Screen. Siren public API on /api/v1/. Auth is Bearer sk_live_ or sk_test_. See https://mysiren.ai/api and https://mysiren.ai/openapi.json." } }, "/api/v1/programmatic/brand-dna": { "get": { "tags": [ "programmatic" ], "summary": "Programmatic Get Brand Dna", "description": "Read this key's Brand DNA (kit + offer + product map). Not Brand Memory.", "operationId": "programmatic_get_brand_dna_api_v1_programmatic_brand_dna_get", "parameters": [ { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Programmatic Get Brand Dna Api V1 Programmatic Brand Dna Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "programmatic" ], "summary": "Programmatic Patch Brand Dna", "description": "Merge fields onto Brand DNA. Send only what changed: tagline, overview,\noffer (product_name, one_liner, features, who_its_for), product_map,\nicp, palette, logos as https URLs. Does not expose Brand Memory.", "operationId": "programmatic_patch_brand_dna_api_v1_programmatic_brand_dna_patch", "parameters": [ { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "title": "Response Programmatic Patch Brand Dna Api V1 Programmatic Brand Dna Patch" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/programmatic/clarify": { "post": { "tags": [ "programmatic" ], "summary": "Programmatic Clarify", "description": "Same vagueness gate the dashboard runs, on the API-key surface.\n\nThe intake logic has always lived in siren_core.campaign_clarifier, but\nonly the session-authed dashboard could reach it \u2014 so an API customer (and\nevery bot we build on this key, Telegram included) sent a one-line brief\nstraight to the planner and got a one-line campaign. Identical intake on\nevery surface was the point of putting it in core; this is the missing half.\n\nStateless, same contract as the dashboard: \"ready\", or up to 2 questions\nwhose answers the caller appends to the brief as a CREATOR PREFERENCES\nblock before calling /generate. Fail-open \u2014 a broken clarifier degrades to\ntoday's behaviour (straight to the planner), it never blocks generation.", "operationId": "programmatic_clarify_api_v1_programmatic_clarify_post", "parameters": [ { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignClarifyRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignClarifyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/programmatic/generate": { "post": { "tags": [ "programmatic" ], "summary": "Programmatic Generate", "operationId": "programmatic_generate_api_v1_programmatic_generate_post", "parameters": [ { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgrammaticGenerateRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgrammaticRunResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Programmatic Generate. Siren public API on /api/v1/. Auth is Bearer sk_live_ or sk_test_. See https://mysiren.ai/api and https://mysiren.ai/openapi.json." } }, "/api/v1/programmatic/me": { "get": { "tags": [ "programmatic" ], "summary": "Programmatic Introspect", "description": "Introspect the bearer key's scopes + workspace. Useful for SDK clients\nto verify what they're authorised to do before making real calls.", "operationId": "programmatic_introspect_api_v1_programmatic_me_get", "parameters": [ { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "title": "Response Programmatic Introspect Api V1 Programmatic Me Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/programmatic/render": { "post": { "tags": [ "programmatic" ], "summary": "Programmatic Render", "description": "Accept pre-formed SirenSeed bodies and queue renders directly \u2014 no LLM.\n\nBypasses the reasoner entirely. Each item must supply a valid seed body for\nthe given output_type. Validation, slogan-lock, and watermark-gate are\napplied server-side; the caller cannot override them.", "operationId": "programmatic_render_api_v1_programmatic_render_post", "parameters": [ { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgrammaticRenderRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgrammaticRenderResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/programmatic/runs": { "get": { "tags": [ "programmatic" ], "summary": "Programmatic List Runs", "description": "List runs for this key's workspace. Newest first.\n\nScoped to runs created via the programmatic API (api_key_id IS NOT NULL)\nOR runs created in the same workspace via the dashboard \u2014 customer's call.\nFor v1 we expose ALL runs in the workspace so customers can audit what\nteammates did via the dashboard. Filter via `?created_via=api` flag if\nthey want only their own programmatic runs (Day 5 polish).\n\nArchived runs (created > 90 days ago, see migration 0033 + the\n`[L1/MA/Render] Lifecycle policy` entry) are filtered out by default.\nPass `include_archived=true` to retrieve them \u2014 useful for backfill /\naudit / SDK clients that want to mirror the workspace's full history.", "operationId": "programmatic_list_runs_api_v1_programmatic_runs_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Archived" } }, { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProgrammaticRunResponse" }, "title": "Response Programmatic List Runs Api V1 Programmatic Runs Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/programmatic/runs/{run_id}": { "get": { "tags": [ "programmatic" ], "summary": "Programmatic Get Run", "operationId": "programmatic_get_run_api_v1_programmatic_runs__run_id__get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Run Id" } }, { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgrammaticRunResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Programmatic Get Run. Siren public API on /api/v1/. Auth is Bearer sk_live_ or sk_test_. See https://mysiren.ai/api and https://mysiren.ai/openapi.json." } }, "/api/v1/programmatic/runs/{run_id}/post": { "post": { "tags": [ "programmatic" ], "summary": "Programmatic Post Run", "description": "Ship an approved run to a connected social account.\n\nUsed by customers whose key has auto_post=False (the default) \u2014 they\nreview the simulation result, then trigger the post when ready.", "operationId": "programmatic_post_run_api_v1_programmatic_runs__run_id__post_post", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Run Id" } }, { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgrammaticPostRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "title": "Response Programmatic Post Run Api V1 Programmatic Runs Run Id Post Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/programmatic/runs/{run_id}/schedule": { "post": { "tags": [ "programmatic" ], "summary": "Programmatic Schedule Run", "description": "Queue a finished run to post at scheduled_at (UTC). Sequential per platform.", "operationId": "programmatic_schedule_run_api_v1_programmatic_runs__run_id__schedule_post", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Run Id" } }, { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgrammaticScheduleRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "title": "Response Programmatic Schedule Run Api V1 Programmatic Runs Run Id Schedule Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/programmatic/studio/custom-templates": { "get": { "tags": [ "studio-custom-templates" ], "summary": "Programmatic List Custom Templates", "operationId": "programmatic_list_custom_templates_api_v1_programmatic_studio_custom_templates_get", "parameters": [ { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioCustomTemplateListOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Programmatic List Custom Templates. Siren public API on /api/v1/. Auth is Bearer sk_live_ or sk_test_. See https://mysiren.ai/api and https://mysiren.ai/openapi.json." } }, "/api/v1/programmatic/studio/custom-templates/import": { "post": { "tags": [ "studio-custom-templates" ], "summary": "Programmatic Import Custom Template", "operationId": "programmatic_import_custom_template_api_v1_programmatic_studio_custom_templates_import_post", "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "title": "Name" } }, { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_programmatic_import_custom_template_api_v1_programmatic_studio_custom_templates_import_post" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioCustomTemplateOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Programmatic Import Custom Template. Siren public API on /api/v1/. Auth is Bearer sk_live_ or sk_test_. See https://mysiren.ai/api and https://mysiren.ai/openapi.json." } }, "/api/v1/programmatic/studio/custom-templates/{template_id}": { "get": { "tags": [ "studio-custom-templates" ], "summary": "Programmatic Get Custom Template", "operationId": "programmatic_get_custom_template_api_v1_programmatic_studio_custom_templates__template_id__get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Template Id" } }, { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioCustomTemplateOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Programmatic Get Custom Template. Siren public API on /api/v1/. Auth is Bearer sk_live_ or sk_test_. See https://mysiren.ai/api and https://mysiren.ai/openapi.json." } }, "/api/v1/programmatic/studio/custom-templates/{template_id}/activate": { "post": { "tags": [ "studio-custom-templates" ], "summary": "Programmatic Activate Custom Template", "operationId": "programmatic_activate_custom_template_api_v1_programmatic_studio_custom_templates__template_id__activate_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Template Id" } }, { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioCustomTemplateOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Programmatic Activate Custom Template. Siren public API on /api/v1/. Auth is Bearer sk_live_ or sk_test_. See https://mysiren.ai/api and https://mysiren.ai/openapi.json." } }, "/api/v1/programmatic/studio/custom-templates/{template_id}/refine": { "post": { "tags": [ "studio-custom-templates" ], "summary": "Programmatic Refine Custom Template", "operationId": "programmatic_refine_custom_template_api_v1_programmatic_studio_custom_templates__template_id__refine_post", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Template Id" } }, { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioTemplateRefineRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioCustomTemplateOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Programmatic Refine Custom Template. Siren public API on /api/v1/. Auth is Bearer sk_live_ or sk_test_. See https://mysiren.ai/api and https://mysiren.ai/openapi.json." } }, "/api/v1/ready": { "get": { "tags": [ "health" ], "summary": "Ready", "description": "Liveness probe \u2014 `/ready` semantically means \"this process is alive\nand accepting traffic.\" It is intentionally cheaper than `/health`:\nit does NOT touch the DB / Redis / queue, so a slow dep can't make\nit return 503.\n\nUse case (LB-drain on deploy): when systemd sends SIGTERM, the\ngraceful-shutdown handler flips an internal flag so `/ready` starts\nreturning 503 \u2014 the load balancer pulls this instance out of\nrotation while in-flight requests drain. Today (single-server,\nnginx-direct), there's no LB drain \u2014 `/ready` is here for the\nconvention so day-1 multi-host deploys work without code change.", "operationId": "ready_api_v1_ready_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "title": "Response Ready Api V1 Ready Get" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/studio/generate": { "post": { "tags": [ "studio" ], "summary": "Studio Generate", "operationId": "studio_generate_api_v1_studio_generate_post", "parameters": [ { "name": "X-Siren-Key-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Id" } }, { "name": "X-Siren-Key-Workspace-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Workspace-Id" } }, { "name": "X-Siren-Key-Scopes", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Siren-Key-Scopes" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioGenerateRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioGenerateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "400": { "description": "Bad request. Typed Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Credits or plan gate. Message names the upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run or resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (idempotency replay mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Honor Retry-After and RateLimit-*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Studio Generate. Siren public API on /api/v1/. Auth is Bearer sk_live_ or sk_test_. See https://mysiren.ai/api and https://mysiren.ai/openapi.json." } } }, "components": { "schemas": { "Body_programmatic_import_custom_template_api_v1_programmatic_studio_custom_templates_import_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_programmatic_import_custom_template_api_v1_programmatic_studio_custom_templates_import_post" }, "CampaignClarifyRequest": { "properties": { "brief": { "type": "string", "maxLength": 8000, "minLength": 1, "title": "Brief" }, "has_screenshot": { "type": "boolean", "title": "Has Screenshot", "default": false } }, "type": "object", "required": [ "brief" ], "title": "CampaignClarifyRequest" }, "CampaignClarifyResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "questions": { "items": { "$ref": "#/components/schemas/ClarifyQuestion" }, "type": "array", "title": "Questions", "default": [] }, "screenshot_ask": { "anyOf": [ { "$ref": "#/components/schemas/ScreenshotAsk" }, { "type": "null" } ] } }, "type": "object", "required": [ "status" ], "title": "CampaignClarifyResponse" }, "ClarifyOption": { "properties": { "value": { "type": "string", "maxLength": 64, "title": "Value" }, "label": { "type": "string", "maxLength": 48, "title": "Label" } }, "type": "object", "required": [ "value", "label" ], "title": "ClarifyOption" }, "ClarifyQuestion": { "properties": { "id": { "type": "string", "maxLength": 32, "title": "Id" }, "question": { "type": "string", "maxLength": 200, "title": "Question" }, "options": { "items": { "$ref": "#/components/schemas/ClarifyOption" }, "type": "array", "maxItems": 6, "minItems": 2, "title": "Options" }, "multi": { "type": "boolean", "title": "Multi", "default": false } }, "type": "object", "required": [ "id", "question", "options" ], "title": "ClarifyQuestion" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ProgrammaticGenerateRequest": { "properties": { "brief": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Brief" }, "channel": { "type": "string", "maxLength": 80, "title": "Channel", "default": "twitter" }, "asset_type": { "type": "string", "title": "Asset Type", "default": "card" }, "extra": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Extra" }, "scheduled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Scheduled At" }, "timezone": { "type": "string", "maxLength": 64, "title": "Timezone", "default": "UTC" }, "platforms": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 12 }, { "type": "null" } ], "title": "Platforms" }, "captions": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Captions" }, "skip_cta_reply": { "type": "boolean", "title": "Skip Cta Reply", "default": false } }, "type": "object", "required": [ "brief" ], "title": "ProgrammaticGenerateRequest" }, "ProgrammaticPostRequest": { "properties": { "platform": { "type": "string", "title": "Platform", "default": "x" } }, "type": "object", "title": "ProgrammaticPostRequest" }, "ProgrammaticRenderRequest": { "properties": { "items": { "items": { "$ref": "#/components/schemas/SeedRenderItem" }, "type": "array", "maxItems": 10, "minItems": 1, "title": "Items" }, "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Name" } }, "type": "object", "required": [ "items" ], "title": "ProgrammaticRenderRequest" }, "ProgrammaticRenderResponse": { "properties": { "run_ids": { "items": { "type": "string" }, "type": "array", "title": "Run Ids" }, "poll_url": { "type": "string", "title": "Poll Url" } }, "type": "object", "required": [ "run_ids", "poll_url" ], "title": "ProgrammaticRenderResponse" }, "ProgrammaticRunResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "status": { "type": "string", "title": "Status" }, "brief": { "type": "string", "title": "Brief" }, "channel": { "type": "string", "title": "Channel" }, "asset_type": { "type": "string", "title": "Asset Type" }, "output_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Text" }, "asset_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Asset Url" }, "asset_urls": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Asset Urls" }, "impact_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Impact Score" }, "verdict": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Verdict" }, "audience_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Audience Score" }, "audience_verdict": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audience Verdict" }, "audience_themes": { "anyOf": [ { "items": { "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Audience Themes" }, "audience_risks": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Audience Risks" }, "audience_opportunities": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Audience Opportunities" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At" }, "auto_post_eligible": { "type": "boolean", "title": "Auto Post Eligible", "description": "True if this run was created with a key whose auto_post=True. The post is dispatched as soon as the run finishes rendering." }, "scheduled": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Scheduled" } }, "type": "object", "required": [ "id", "status", "brief", "channel", "asset_type", "output_text", "asset_url", "created_at", "started_at", "finished_at", "auto_post_eligible" ], "title": "ProgrammaticRunResponse", "description": "Subset of PipelineRunResponse exposed via the public API.\n\nStable shape we commit to \u2014 internal columns (input_brief raw structure,\ncost_cents, current_stage) are kept off this surface so we can refactor\nthem later without breaking customer integrations." }, "ProgrammaticScheduleRequest": { "properties": { "scheduled_at": { "type": "string", "format": "date-time", "title": "Scheduled At" }, "timezone": { "type": "string", "maxLength": 64, "title": "Timezone", "default": "UTC" }, "platforms": { "items": { "type": "string" }, "type": "array", "maxItems": 12, "title": "Platforms" }, "captions": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Captions" }, "skip_cta_reply": { "type": "boolean", "title": "Skip Cta Reply", "default": false }, "force": { "type": "boolean", "title": "Force", "default": false } }, "type": "object", "required": [ "scheduled_at" ], "title": "ProgrammaticScheduleRequest" }, "ProgrammaticScreenIn": { "properties": { "name": { "type": "string", "maxLength": 80, "minLength": 1, "title": "Name" }, "screen_type": { "type": "string", "maxLength": 40, "title": "Screen Type", "default": "feature" }, "device": { "type": "string", "maxLength": 16, "title": "Device", "default": "phone" }, "theme": { "type": "string", "maxLength": 16, "title": "Theme", "default": "unknown" }, "image_url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Image Url" }, "image_base64": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image Base64" } }, "type": "object", "required": [ "name" ], "title": "ProgrammaticScreenIn" }, "ScreenshotAsk": { "properties": { "recommended": { "type": "boolean", "title": "Recommended", "default": true }, "status": { "type": "string", "title": "Status", "default": "suggest" }, "title": { "type": "string", "title": "Title", "default": "" }, "prompt": { "type": "string", "title": "Prompt", "default": "" }, "examples": { "items": { "type": "string" }, "type": "array", "title": "Examples", "default": [] }, "can_skip": { "type": "boolean", "title": "Can Skip", "default": true }, "importance": { "type": "string", "title": "Importance", "default": "medium" }, "label": { "type": "string", "title": "Label", "default": "" }, "output_types": { "items": { "type": "string" }, "type": "array", "title": "Output Types", "default": [] }, "options": { "items": { "$ref": "#/components/schemas/ClarifyOption" }, "type": "array", "title": "Options", "default": [] } }, "type": "object", "title": "ScreenshotAsk", "description": "Soft coach: real UI capture would improve this render. Never blocking." }, "SeedRenderItem": { "properties": { "output_type": { "type": "string", "maxLength": 120, "title": "Output Type" }, "channel": { "type": "string", "maxLength": 80, "title": "Channel", "default": "twitter" }, "seed_body": { "type": "object", "title": "Seed Body" }, "archetype": { "type": "string", "maxLength": 80, "title": "Archetype", "default": "builder" }, "family": { "type": "string", "maxLength": 80, "title": "Family", "default": "pillar" }, "surface": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ], "title": "Surface" }, "caption": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Caption" }, "brand_override": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Brand Override" }, "voice_id": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Voice Id" } }, "type": "object", "required": [ "output_type", "seed_body" ], "title": "SeedRenderItem" }, "StudioCustomTemplateListOut": { "properties": { "items": { "items": { "$ref": "#/components/schemas/StudioCustomTemplateOut" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "items" ], "title": "StudioCustomTemplateListOut" }, "StudioCustomTemplateOut": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "status": { "type": "string", "title": "Status" }, "layer_stack_json": { "type": "object", "title": "Layer Stack Json" }, "convergence_round_count": { "type": "integer", "title": "Convergence Round Count" }, "preview_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Preview Url" } }, "type": "object", "required": [ "id", "name", "status", "layer_stack_json", "convergence_round_count", "preview_url" ], "title": "StudioCustomTemplateOut" }, "StudioGenerateRequest": { "properties": { "design_id": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "title": "Design Id" }, "output_type": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Output Type" }, "data": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Data" }, "caption": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Caption" }, "delivery": { "type": "string", "pattern": "^(auto|download)$", "title": "Delivery", "default": "auto" }, "channel": { "type": "string", "maxLength": 80, "title": "Channel", "default": "twitter" }, "surface": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "title": "Surface" } }, "type": "object", "title": "StudioGenerateRequest", "description": "Fire a Studio render.\n\nTwo equally valid shapes:\n\n1. **design_id** (preferred, frictionless) \u2014 reference a saved Studio\n design. Optional ``data`` shallow-merges over the saved body so event\n values (pnl, price, handle\u2026) can change without re-shipping the full\n seed. One workspace API key + one Studio profile covers every design.\n2. **output_type + data** \u2014 legacy / explicit full body (wizard snippets)." }, "StudioGenerateResponse": { "properties": { "run_id": { "type": "string", "title": "Run Id" }, "poll_url": { "type": "string", "title": "Poll Url" }, "delivery": { "items": { "type": "string" }, "type": "array", "title": "Delivery" } }, "type": "object", "required": [ "run_id", "poll_url", "delivery" ], "title": "StudioGenerateResponse" }, "StudioTemplateRefineRequest": { "properties": { "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "message" ], "title": "StudioTemplateRefineRequest" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "Error": { "type": "object", "title": "Error", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "Machine-readable code (rate_limited, plan_required, unauthorized)." }, "message": { "type": "string", "description": "Human-readable explanation safe to show an operator." }, "detail": { "description": "Optional structured extra (field errors, plan slug, retry hint)." } } } } }, "tags": [ { "name": "programmatic", "description": "Bearer-key generate / render / post." }, { "name": "health", "description": "Liveness and dependency probes." }, { "name": "studio", "description": "Event cards from a saved design_id." } ] }