swagger: "2.0" info: title: copydesk-api description: CopyDesk API version: 1.1.0 schemes: - https produces: - application/json x-google-backend: address: https://us-central1-monks-uber-copydesk.cloudfunctions.net/api path_translation: APPEND_PATH_TO_ADDRESS protocol: h2 deadline: 300 jwt_audience: https://us-central1-monks-uber-copydesk.cloudfunctions.net/api paths: /api/generate-copy: post: summary: Generate Copy description: Starts or continues a copy generation thread parameters: - name: body in: body required: true schema: type: object required: - presetId - brandId - prompt - campaignId - subThemeId - merchant - offerTypeId - minimumSpend - expirationDate properties: presetId: type: string description: The preset to use brandId: type: string description: The ID of the brand to generate copy for prompt: type: string description: The prompt for the copy generation campaignId: type: string description: The ID of the campaign to generate copy for subThemeId: type: string description: The ID of the sub-theme to use merchant: type: string description: The name of the merchant of the offer offerTypeId: type: string description: The ID of the type of offer product: type: string description: The name of the product of the offer, applies to bogo and free-item type offers offerAmount: type: number description: The percentage or dollar amount for a percent-off or dollar-off type offer discountLimit: type: number description: The maximum discount amount for the offer, applies to percent-off type offers minimumSpend: type: number description: Minimum total spend amount for the offer to apply expirationDate: type: string description: The expiration date for the offer isMemberExclusive: type: boolean description: Whether the offer is member exclusive default: false subjectLineMustIncludeMerchant: type: boolean description: Whether the email subject line must include the merchant name default: false countryId: type: string description: The ID of the country the copy is for enum: - us - ca default: us languageId: type: string description: The ID of the language to use enum: - en-us - fr-fr default: en-us temperature: type: number description: The temperature value for the copy generation minimum: 0 maximum: 1 default: 0.5 threadId: type: string description: The ID of the conversation thread to continue config: type: object description: A set of configuration override options that control strategy, platform, model etc. properties: platform: type: string description: Which platform to use for copy generation. enum: - google - openai - azure default: google embeddingPlatform: type: string description: Which platform to use for generating embeddings. enum: - google - openai - azure default: google model: type: string description: Which model to use for copy generation. Valid values include all models available on the selected platform. Note that for Azure OpenAI this refers to deployment names instead. embeddingModel: type: string description: Which model to use for generating embeddings. Valid values include all embedding models available on the selected embedding platform. strategy: type: string description: Which strategy to use, determining the mode of agent cooperation. Parallel scales better, Serial may improve quality. Auto selects the best strategy based on context. enum: - auto - serial - parallel default: auto forceCopyBasedVectorSearch: type: boolean description: When enabled, initial run vector searches will wait for the Draft agent to complete. May improve quality at the cost of a slower first response. Has no effect on follow-up runs. default: true ignoreFixedAgentOrder: type: boolean description: When enabled, the standard order for Serial generation (Brand > Product > Tone of Voice > Target Audience > Channel) will be ignored to improve performance. Might reduce quality. Has no effect in Parallel mode. default: false examplesTopN: type: integer description: Sets the amount of examples that will be used. default: 3 minimum: 0 brandContextTopN: type: integer description: Sets the amount of results that will be included in the Brand Context. default: 3 minimum: 0 disableBrandContext: type: boolean description: Disables the vector search for Brand Context, relying only on the static Brand Guidelines. Greatly increases speed, but might reduce quality. default: false waitForThreadUpdate: type: boolean description: Waits for the thread to be updated in the database before returning a response. Significantly slows down responses, but eliminates the risk of an Invalid threadId error or missing context when immediately sending a follow-up request. default: false responses: "200": description: Successful response schema: type: object properties: error: type: string description: Error message if applicable, otherwise null. copy: type: object description: The generated copy. textResponse: type: string description: Text response if applicable, otherwise null. threadId: type: string format: uuid description: Unique identifier for the thread. revisionRecord: type: array items: type: object additionalProperties: type: string description: List of revision notes detailing changes made to the copy by the active agents. config: type: object properties: prompt: type: string description: The provided user prompt. brandId: type: string description: The provided brand ID. productId: type: string description: The provided product ID. toneOfVoiceId: type: string description: The provided tone of voice ID. targetAudienceId: type: string description: The provided target audience ID. temperature: type: number format: float description: The provided temperature setting. languageId: type: string description: The provided language ID. presetId: type: string description: The provided preset ID. maxCharacters: type: integer description: The provided character limit. options: type: object description: The provided options. effectiveOptions: type: object description: The effective options used. debugInfo: type: object properties: history: type: object description: The conversation history. debug: type: array items: type: string description: Debugging-related information, including agent inputs and outputs. performance: type: array items: type: object additionalProperties: type: number description: Performance metrics. generationInfo: type: object properties: prompt: type: string description: The provided user prompt. brandId: type: string description: The provided brand ID. temperature: type: number format: float description: The provided temperature setting. languageId: type: string description: The provided language ID. presetId: type: string description: The provided preset ID. /api/fields/{field}: parameters: - name: field description: The name of the field type: string enum: - brands - campaigns - countries - languages - offer-types - sub-themes in: path required: true get: summary: Retrieve Field Options description: Returns available options for a given field responses: "200": description: Successful response schema: type: array items: type: object properties: id: type: string description: Field ID label: type: string description: Field label description: type: string description: Field description /api/presets: get: summary: Retrieve Presets description: Returns available presets (templates) responses: "200": description: Successful response schema: type: object properties: id: type: string description: Unique identifier for the preset. label: type: string description: User-friendly label describing the preset. description: type: string description: Description of the preset. icon: type: string description: Icon for the preset. /api/thread/{threadId}: parameters: - name: threadId description: The ID of the thread to retrieve type: string in: path required: true get: summary: Retrieve Conversation Thread description: Retrieves a thread containing its conversation history and input and output of the last interaction responses: "200": description: Successful response schema: type: object properties: history: type: array description: The conversation history. context: type: object description: Context used for last generation. copy: type: string description: Output copy of last generation. /api/brand-setup/{brandId}: parameters: - name: brandId description: The ID of the brand type: string in: path required: true post: summary: Set Up Brand description: Performs the brand setup for a given brand parameters: - name: body in: body required: true schema: type: object properties: config: type: object description: A set of options that can be set to control strategy, platform, model etc. properties: platform: type: string description: Which platform to use for copy generation. enum: - google - openai - azure default: google embeddingPlatform: type: string description: Which platform to use for generating embeddings. enum: - google - openai - azure default: google model: type: string description: Which model to use for copy generation. Valid values include all models available on the selected platform. Note that for Azure OpenAI this refers to deployment names instead. embeddingModel: type: string description: Which model to use for generating embeddings. Valid values include all embedding models available on the selected embedding platform. responses: "200": description: Successful response /api/defaults: get: summary: Retrieve Configuration Defaults description: Returns default values for the configuration responses: "200": description: Successful response schema: type: object properties: platform: type: string description: Default value for platform embeddingPlatform: type: string description: Default value for embeddingPlatform strategy: type: string description: Default value for strategy forceCopyBasedVectorSearch: type: boolean description: Default value for forceCopyBasedVectorSearch ignoreFixedAgentOrder: type: boolean description: Default value for ignoreFixedAgentOrder examplesTopN: type: integer description: Default value for examplesTopN simpleChannelContext: type: boolean description: Default value for simpleChannelContext brandContextTopN: type: integer description: Default value for brandContextTopN disableBrandContext: type: boolean description: Default value for disableBrandContext waitForThreadUpdate: type: boolean description: Default value for waitForThreadUpdate securityDefinitions: api_key: type: apiKey name: x-api-key in: header