{"openapi":"3.1.0","info":{"title":"TakeShape REST API","description":"OpenAPI documentation for TakeShape REST API","version":"0.1.0"},"servers":[{"url":"https://api.takeshape.io","description":"API Server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"token","description":"TakeShape API key, PAT or a JWT"}},"schemas":{"CAPChallengeRedeemResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"token":{"type":"string"},"expires":{"type":"number"}},"required":["success"]},"ErrorResponse":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code","examples":[400]},"error":{"type":"string","description":"Error type","examples":["Bad Request"]},"message":{"type":"string","description":"Error message","examples":["Invalid request"]}},"required":["statusCode","error","message"]},"CAPChallengeRedeemBody":{"type":"object","properties":{"token":{"type":"string"},"solutions":{"type":"array","items":{"type":"number"}}},"required":["token","solutions"]},"CAPChallengeResponse":{"type":"object","properties":{"challenge":{"type":"object","properties":{"c":{"type":"number","description":"Challenge code","examples":[123456]},"s":{"type":"number","description":"Challenge seed","examples":[654321]},"d":{"type":"number","description":"Challenge difficulty","examples":[5]}},"required":["c","s","d"]},"token":{"type":"string","description":"Challenge token","examples":["abcdef123456"]},"expires":{"type":"number","description":"Expiration timestamp","examples":[1700000000]}},"required":["challenge","expires"]},"ValidateEmailResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the operation was successful"},"message":{"type":"string","description":"Human-readable result message"}},"required":["success","message"]},"ValidateEmailBody":{"type":"object","properties":{"emailValidationToken":{"type":"string","minLength":1,"description":"Email validation token","examples":["abc-123-def"]},"email":{"type":"string","format":"email","description":"User email address","examples":["user@example.com"]}},"required":["emailValidationToken","email"]},"ResendEmailResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the operation was successful"},"message":{"type":"string","description":"Human-readable result message"}},"required":["success","message"]},"ResendEmailBody":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"User email address","examples":["user@example.com"]}},"required":["email"]},"BigCommerceChannelsResponse":{"type":"object","properties":{"channels":{"type":"array","items":{"$ref":"#/components/schemas/BigCommerceChannel"},"description":"List of BigCommerce channels with configuration status"}},"required":["channels"]},"BigCommerceChannel":{"type":"object","properties":{"id":{"type":"number","description":"Channel ID"},"name":{"type":"string","description":"Channel name"},"type":{"type":"string","description":"Channel type"},"platform":{"type":"string","description":"Channel platform"},"status":{"type":"string","description":"Channel status"},"isEnabled":{"type":"boolean","description":"Whether the channel is enabled"},"isConfigured":{"type":"boolean","description":"Whether the channel has a TakeShape project configured"},"siteUrl":{"type":"string","format":"uri","description":"Channel site URL if available"},"projectId":{"type":"string","description":"TakeShape project ID if configured"},"token":{"type":"string","description":"API token for the TakeShape project if configured"}},"required":["id","name","type","platform","status","isEnabled","isConfigured"]},"BigCommerceCreateChannelBody":{"type":"object","properties":{"channelId":{"type":"number","description":"BigCommerce channel ID","examples":[1]},"channelName":{"type":"string","description":"BigCommerce channel name","examples":["My Storefront"]}},"required":["channelId","channelName"]},"AgentsResponse":{"type":"object","properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/Agent"},"description":"List of BigCommerce agents with configuration status"}},"required":["agents"]},"Agent":{"type":"object","properties":{"id":{"type":"string","description":"The encoded ID of the agent"},"name":{"type":"string","description":"The name of the agent"},"title":{"type":"string","description":"The title of the agent"},"description":{"type":"string","description":"The description of the agent"},"status":{"type":"string","enum":["active","disabled"],"description":"The status of the agent"},"systemPrompt":{"type":"string","description":"Custom system prompt for the agent"},"systemPromptDefault":{"type":"string","description":"Default system prompt for the agent"},"inputName":{"type":"string","description":"The name of the BigCommerce API input associated with the agent"},"targetSelector":{"type":"string","description":"CSS selector for where the agent should be active"},"targetSelectorDefault":{"type":"string","description":"Default CSS selector for where the agent should be active"}},"required":["id","name","title","description","status","systemPromptDefault","inputName","targetSelectorDefault"]},"AgentUpdateBody":{"type":"object","properties":{"systemPrompt":{"type":["string","null"],"description":"Custom system prompt for the agent. Pass null to clear."},"disabled":{"type":["boolean","null"],"description":"Whether the agent is disabled. Pass true to disable, false to enable."},"targetSelector":{"type":["string","null"],"description":"CSS selector for where the agent should be active. Pass null to clear."}}},"BulkOperationResponse":{"type":"object","properties":{"channelsUpdated":{"type":"number","description":"Number of channels updated"},"agentsUpdated":{"type":"number","description":"Number of agents updated"}},"required":["channelsUpdated","agentsUpdated"]},"ThreadListResponse":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/ThreadResponse"},"description":"List of active threads for the agent"}},"required":["threads"]},"ThreadResponse":{"type":"object","properties":{"id":{"type":"string","description":"The unique session/thread ID","examples":["01234567-89ab-cdef-0123-456789abcdef"]},"agentName":{"type":"string","description":"The name of the agent","examples":["my-agent"]},"status":{"type":"string","enum":["created","started","suspended","done"],"description":"The status of the agent thread","examples":["created"]},"schemaId":{"type":"string","description":"The schema ID associated with the thread"},"schemaHash":{"type":"string","description":"The schema hash for version tracking"},"createdAt":{"type":"string","description":"ISO timestamp when the thread was created","examples":["2024-01-01T12:00:00Z"]},"updatedAt":{"type":"string","description":"ISO timestamp when the thread was last updated","examples":["2024-01-01T12:05:00Z"]},"firstMessageInput":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"string"},"content":{"type":"string"}},"required":["type","content"]},{"type":"object","properties":{"type":{"type":"string","const":"unknown"},"data":{}},"required":["type"]}],"description":"The input of the first message in the thread, or empty if no messages yet"},"duration":{"type":"number","description":"Duration of the thread in milliseconds, only set when status is done"},"lastMessageOutput":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"generate"},"data":{}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"graphql"},"data":{}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"chat"},"data":{"type":"object","properties":{"content":{"type":"string","description":"The text content of the chat message"},"artifact":{"type":"object","additionalProperties":{},"description":"Optional artifacts associated with the chat message"},"references":{"type":"array","items":{"type":"object","properties":{"_tid":{"type":"string","description":"The thread ID that this message references","examples":["01234567-89ab-cdef-0123-456789abcdef"]}},"required":["_tid"]},"description":"References to other threads or messages"}},"required":["content","references"]}},"required":["type","data"]},{"type":"object","properties":{"type":{"type":"string","const":"unknown"},"data":{}},"required":["type"]}],"description":"The output of the last message in the thread, if available"}},"required":["id","agentName","status","schemaId","schemaHash","createdAt","updatedAt"]},"StatsResponse":{"type":"object","properties":{"activeAgents":{"type":"number","description":"Number of active agents configured for this channel"},"threadsLast30Days":{"type":"number","description":"Number of agent threads created in the last 30 days"},"tokenUsage":{"type":"array","items":{"$ref":"#/components/schemas/TokenUsageSummary"},"description":"Token usage summary by service and model"}},"required":["activeAgents","threadsLast30Days","tokenUsage"]},"TokenUsageSummary":{"type":"object","properties":{"service":{"type":"string","description":"AI service provider (e.g., openai, anthropic)"},"model":{"type":"string","description":"Model identifier"},"totalInputTokens":{"type":"number","description":"Total input tokens used"},"totalOutputTokens":{"type":"number","description":"Total output tokens used"},"totalTokens":{"type":"number","description":"Total tokens used"},"count":{"type":"number","description":"Number of API calls"}},"required":["service","model","totalInputTokens","totalOutputTokens","totalTokens","count"]},"TokenRefreshResponse":{"type":"object","properties":{"access_token":{"type":"string","description":"New store token JWT","examples":["eyJ..."]},"token_type":{"type":"string","const":"Bearer","description":"Token type"},"expires_in":{"type":"number","description":"Token lifetime in seconds","examples":[1200]}},"required":["access_token","token_type","expires_in"]},"CreateThreadBody":{"type":"object","properties":{"agentName":{"type":"string","description":"The name of the agent to create a thread for","examples":["my-agent"]}},"required":["agentName"]},"CreateMessageBody":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/UiMessage"},"minItems":1,"description":"Array of UI messages to send to the agent"},"id":{"type":"string","description":"The thread/session ID","examples":["01234567-89ab-cdef-0123-456789abcdef"]},"trigger":{"type":"string","description":"Optional trigger for the message"},"metadata":{"$ref":"#/components/schemas/ThreadMetadata"}},"required":["messages","id","metadata"]},"UiMessage":{"type":"object","properties":{"parts":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/TextUIPart"},{"$ref":"#/components/schemas/FileUIPart"},{"$ref":"#/components/schemas/ToolUIPart"},{"$ref":"#/components/schemas/OtherUIPart"}]},"minItems":1,"description":"Array of message parts (text, file, tool, or other)"},"id":{"type":"string","description":"Optional message ID"},"role":{"type":"string","enum":["system","user","assistant"],"description":"The role of the message sender","examples":["user"]}},"required":["parts","role"]},"TextUIPart":{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","description":"The text content of the message part","examples":["Hello, how can I help you today?"]}},"required":["type","text"]},"FileUIPart":{"type":"object","properties":{"type":{"type":"string","const":"file"},"mediaType":{"type":"string","description":"MIME type of the file","examples":["image/png"]},"filename":{"type":"string","description":"Optional filename"},"url":{"type":"string","description":"Data URL or URL to the file","examples":["data:image/png;base64,..."]}},"required":["type","mediaType","url"]},"ToolUIPart":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","pattern":"^tool-"},{"type":"string","const":"dynamic-tool"}],"description":"The type of tool part","examples":["tool-askQuestion","tool-searchProducts"]},"toolName":{"type":"string","description":"The name of the tool","examples":["askQuestion","searchProducts"]},"toolCallId":{"type":"string","description":"The unique tool call ID","examples":["toolu_01ABC123"]},"state":{"type":"string","enum":["input-streaming","input-available","output-available","output-error"],"description":"The state of the tool call"},"input":{"description":"Optional tool input parameters"},"output":{"description":"Optional tool output result"}},"required":["type","toolName","toolCallId","state"]},"OtherUIPart":{"type":"object","properties":{"type":{"type":"string","description":"The type of UI part"}},"required":["type"]},"ThreadMetadata":{"type":"object","properties":{"custom":{"type":"object","properties":{"inputName":{"type":"string","description":"The name of the input field for the agent","examples":["userInput"]}},"required":["inputName"]}},"required":["custom"]}}},"tags":[{"name":"Authentication","description":"OAuth and session management endpoints"},{"name":"Setup","description":"Store and channel configuration endpoints"},{"name":"Email Verification","description":"BigCommerce user email verification endpoints"},{"name":"Agent","description":"AI agent endpoints"},{"name":"BigCommrerce","description":"BigCommerce integration endpoints"}],"paths":{"/protection/cap/redeem":{"post":{"operationId":"postProtectionCapRedeem","tags":["Protection"],"summary":"CAP challenge redeem","description":"Redeems a previously issued CAP challenge using the provided token and solutions.","responses":{"200":{"description":"CAP Challenge redemption response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CAPChallengeRedeemResponse"}}}},"400":{"description":"Invalid request - unable to redeem challenge","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CAPChallengeRedeemBody"}}}}}},"/protection/cap/challenge":{"post":{"operationId":"postProtectionCapChallenge","tags":["Protection"],"summary":"CAP challenge","description":"Gets a new CAP challenge to be solved by the client.","responses":{"200":{"description":"CAP Challenge response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CAPChallengeResponse"}}}}}}},"/bigcommerce/auth":{"get":{"operationId":"authBigcommerceApp","tags":["Authentication"],"summary":"BigCommerce OAuth callback","description":"OAuth callback endpoint called by BigCommerce when the app is installed. Exchanges the authorization code for an access token and sets up the user account.","responses":{"302":{"description":"Redirect to setup page or app"},"400":{"description":"Invalid OAuth parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"query","name":"code","schema":{"type":"string","examples":["abc123"]},"description":"OAuth authorization code from BigCommerce"},{"in":"query","name":"scope","schema":{"type":"string","examples":["store_v2_content"]},"description":"OAuth scopes granted"},{"in":"query","name":"context","schema":{"type":"string","examples":["stores/abc123"]},"description":"Store context identifier"},{"in":"query","name":"dev_token","schema":{"type":"string","examples":["eyJ..."]},"description":"Dev auth token for local development"},{"in":"query","name":"external_resources_disabled","schema":{"type":"string"},"description":"Disable external resource creation for testing"}]}},"/bigcommerce/load":{"get":{"operationId":"loadBigcommerceApp","tags":["Authentication"],"summary":"Load BigCommerce app","description":"Called by BigCommerce each time the app is opened. Verifies the signed JWT payload and redirects to the appropriate page based on configuration status.","responses":{"302":{"description":"Redirect to app, setup page, or email verification page"},"400":{"description":"Invalid payload or app not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"query","name":"signed_payload_jwt","schema":{"type":"string","examples":["eyJ..."]},"description":"BigCommerce signed payload JWT"},{"in":"query","name":"dev_token","schema":{"type":"string","examples":["eyJ..."]},"description":"Dev auth token for local development"}]}},"/bigcommerce/uninstall":{"get":{"operationId":"uninstallBigcommerceApp","tags":["Setup"],"summary":"Uninstall BigCommerce app","description":"Called by BigCommerce when the app is uninstalled. Cleans up all TakeShape resources including projects, API keys, and BigCommerce scripts/pages.","responses":{"204":{"description":"App uninstalled successfully"},"400":{"description":"Invalid payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"query","name":"signed_payload_jwt","schema":{"type":"string","examples":["eyJ..."]},"description":"BigCommerce signed payload JWT"},{"in":"query","name":"dev_token","schema":{"type":"string","examples":["eyJ..."]},"description":"Dev auth token for local development"}]}},"/bigcommerce/validate-email":{"post":{"operationId":"validateBigcommerceEmail","tags":["Email Verification"],"summary":"Validate user email","description":"Validates a user email address using a verification token sent via email.","responses":{"200":{"description":"Email validated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateEmailResponse"}}}},"400":{"description":"Invalid verification request or token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateEmailBody"}}}}}},"/bigcommerce/resend-email":{"post":{"operationId":"resendBigcommerceVerificationEmail","tags":["Email Verification"],"summary":"Resend verification email","description":"Resends the email verification link to the specified email address.","responses":{"200":{"description":"Email sent if account exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendEmailResponse"}}}},"400":{"description":"Unable to send verification email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendEmailBody"}}}}}},"/bigcommerce/channels":{"get":{"operationId":"getBigcommerceChannels","tags":["Setup"],"summary":"Get BigCommerce channels","description":"Fetches all available BigCommerce channels for the store and indicates which ones have TakeShape projects configured.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of channels with configuration status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BigCommerceChannelsResponse"}}}},"401":{"description":"Unauthorized - invalid or missing store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createBigcommerceChannel","tags":["Setup"],"summary":"Configure BigCommerce channel","description":"Sets up a TakeShape project for a specific BigCommerce channel. Creates the project if needed, configures API keys, and installs BigCommerce scripts and pages.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of channels with configuration status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BigCommerceChannel"}}}},"400":{"description":"Invalid request - missing or invalid channelId/channelName, or associated BigCommerce channel not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BigCommerceCreateChannelBody"}}}}}},"/bigcommerce/channels/{channelId}/agents":{"get":{"operationId":"getBigcommerceAgents","tags":["Agent","BigCommerce"],"summary":"Get BigCommerce agents","description":"Fetches all available BigCommerce agents for the store and channel.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of agents with configuration status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsResponse"}}}},"400":{"description":"Bad Request - invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"channelId","schema":{"type":"number","examples":[1]},"required":true,"description":"The unique identifier for a channel"}]}},"/bigcommerce/channels/{channelId}/agents/{agentId}":{"get":{"operationId":"getBigcommerceAgent","tags":["Agent","BigCommerce"],"summary":"Get BigCommerce agent","description":"Fetches a specific BigCommerce agent for the store and channel.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Agent with configuration status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"Bad Request - invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"channelId","schema":{"type":"number","examples":[1]},"required":true,"description":"The unique identifier for a channel"},{"in":"path","name":"agentId","schema":{"type":"string","examples":["purchaseOrderAgent"]},"required":true,"description":"The name of the AI agent"}]},"put":{"operationId":"updateBigcommerceAgent","tags":["Agent","BigCommerce"],"summary":"Update BigCommerce agent","description":"Updates a specific BigCommerce agent configuration.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Updated agent with configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"Bad Request - invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"channelId","schema":{"type":"number","examples":[1]},"required":true,"description":"The unique identifier for a channel"},{"in":"path","name":"agentId","schema":{"type":"string","examples":["purchaseOrderAgent"]},"required":true,"description":"The name of the AI agent"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentUpdateBody"}}}}}},"/bigcommerce/channels/{channelId}/agents/{agentId}/reset":{"post":{"operationId":"resetBigcommerceAgent","tags":["Agent","BigCommerce"],"summary":"Reset BigCommerce agent to defaults","description":"Resets a specific BigCommerce agent to pattern defaults, clearing all customizations.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Agent reset to defaults","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"Bad Request - invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - channel or agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"channelId","schema":{"type":"number","examples":[1]},"required":true,"description":"The unique identifier for a channel"},{"in":"path","name":"agentId","schema":{"type":"string","examples":["purchaseOrderAgent"]},"required":true,"description":"The name of the AI agent"}]}},"/bigcommerce/channels/{channelId}/agents/{agentId}/sync":{"post":{"operationId":"syncBigcommerceAgent","tags":["Agent","BigCommerce"],"summary":"Sync BigCommerce agent with pattern","description":"Syncs a specific BigCommerce agent with the latest pattern, preserving customizations.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Agent synced with pattern","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"Bad Request - invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - channel or agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"channelId","schema":{"type":"number","examples":[1]},"required":true,"description":"The unique identifier for a channel"},{"in":"path","name":"agentId","schema":{"type":"string","examples":["purchaseOrderAgent"]},"required":true,"description":"The name of the AI agent"}]}},"/bigcommerce/channels/{channelId}/reset":{"post":{"operationId":"resetBigcommerceChannel","tags":["Agent","BigCommerce"],"summary":"Reset all agents in a channel","description":"Resets all BigCommerce agents in a channel to pattern defaults.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Channel agents reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkOperationResponse"}}}},"400":{"description":"Bad Request - invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - channel or agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"channelId","schema":{"type":"number","examples":[1]},"required":true,"description":"The unique identifier for a channel"}]}},"/bigcommerce/channels/{channelId}/sync":{"post":{"operationId":"syncBigcommerceChannel","tags":["Agent","BigCommerce"],"summary":"Sync all agents in a channel","description":"Syncs all BigCommerce agents in a channel with the latest pattern, preserving customizations.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Channel agents synced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkOperationResponse"}}}},"400":{"description":"Bad Request - invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - channel or agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"channelId","schema":{"type":"number","examples":[1]},"required":true,"description":"The unique identifier for a channel"}]}},"/bigcommerce/channels/{channelId}/threads":{"get":{"operationId":"getBigcommerceThreads","summary":"Get BigCommerce agent threads","description":"Retrieves a list of conversation threads/sessions for AI agents on a BigCommerce channel.","tags":["Agent","BigCommerce"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of threads retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadListResponse"}}}},"400":{"description":"Invalid request - channel does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Channel or schema not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"channelId","schema":{"type":"number","examples":[1]},"required":true,"description":"The unique identifier for a channel"},{"in":"query","name":"first","schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"default":50,"examples":[20]},"description":"Number of items to return"},{"in":"query","name":"last","schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"examples":[20]},"description":"Number of items to return from the end"},{"in":"query","name":"after","schema":{"type":"string","format":"uuid","examples":["550e8400-e29b-41d4-a716-446655440000"]},"description":"Cursor for pagination (returns items after this ID)"},{"in":"query","name":"before","schema":{"type":"string","format":"uuid","examples":["550e8400-e29b-41d4-a716-446655440000"]},"description":"Cursor for pagination (returns items before this ID)"},{"in":"query","name":"query","schema":{"type":"string","default":"","examples":["name:\"myAgent\""]},"description":"Search query (Stripe-style)"},{"in":"query","name":"sort","schema":{"type":"string","enum":["asc","desc"],"default":"asc","examples":["asc"]},"description":"Sort order for pagination"}]}},"/bigcommerce/channels/{channelId}/stats":{"get":{"operationId":"getBigcommerceStats","tags":["Agent","BigCommerce"],"summary":"Get BigCommerce stats","description":"Retrieves statistics for a BigCommerce channel including active agents, session count, and token usage.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Channel statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"400":{"description":"Bad Request - invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"channelId","schema":{"type":"number","examples":[1]},"required":true,"description":"The unique identifier for a channel"}]}},"/bigcommerce/reset":{"post":{"operationId":"resetBigcommerceStore","tags":["Agent","BigCommerce"],"summary":"Reset all channels in a store","description":"Resets all agents in all configured channels to pattern defaults.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Store agents reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkOperationResponse"}}}},"400":{"description":"Bad Request - invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - channel or agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/bigcommerce/sync":{"post":{"operationId":"syncBigcommerceStore","tags":["Agent","BigCommerce"],"summary":"Sync all channels in a store","description":"Syncs all agents in all configured channels with the latest pattern, preserving customizations.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Store agents synced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkOperationResponse"}}}},"400":{"description":"Bad Request - invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - channel or agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/bigcommerce/token/refresh":{"post":{"operationId":"refreshBigcommerceToken","tags":["Auth","BigCommerce"],"summary":"Refresh a BigCommerce store token","description":"Exchanges a valid or recently-expired store token for a fresh one. Accepts tokens that expired up to 5 minutes ago.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"New store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRefreshResponse"}}}},"401":{"description":"Unauthorized - invalid or expired store token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/project/{projectId}/agents/threads":{"post":{"operationId":"createAgentThread","summary":"Create agent thread","description":"Creates a new conversation thread/session for an AI agent. The thread maintains state across multiple messages.","tags":["Agent"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Thread created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadResponse"}}}},"400":{"description":"Invalid request - agent does not exist or has no inputs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Project or schema not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"projectId","schema":{"type":"string","format":"uuid","examples":["550e8400-e29b-41d4-a716-446655440000"]},"required":true,"description":"The unique identifier for a project"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateThreadBody"}}}}}},"/project/{projectId}/agents/messages":{"post":{"operationId":"createAgentMessage","tags":["Agent"],"summary":"Send message to agent","description":"Sends a message to an AI agent thread and streams the response using Server-Sent Events (SSE). The response follows the Vercel AI UI message stream format.","security":[{"bearerAuth":[]}],"servers":[{"url":"https://api.takeshape.io","description":"SSE server for streaming agent responses - varies between prod and dev environments"}],"responses":{"200":{"description":"SSE stream of agent responses","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-Sent Events stream with JSON payloads"}}}},"400":{"description":"Invalid request - missing required message parts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Agent session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"in":"path","name":"projectId","schema":{"type":"string","format":"uuid","examples":["550e8400-e29b-41d4-a716-446655440000"]},"required":true,"description":"The unique identifier for a project"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMessageBody"}}}}}}}}