openapi: 3.0.3
info:
  title: Everflow Network API - Custom Creative Settings
  description: >
    Endpoints for managing custom creative settings in the Everflow network.
    Custom creatives allow you to upload partner-specific creative assets
    that are only visible and usable by the selected partners, enabling
    targeted promotional materials for individual affiliates.
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Custom Creative Settings
paths:
  /networks/custom/creativetable:
    post:
      summary: Find Custom Creative Settings (Advanced)
      tags:
        - Custom Creative Settings
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Page number (1-based).
        - in: query
          name: page_size
          schema:
            type: integer
            default: 50
          description: Number of results per page.
        - in: query
          name: order_field
          schema:
            type: string
            enum:
              - name
              - time_created
              - time_saved
              - id
          description: Field to order results by.
        - in: query
          name: order_direction
          schema:
            type: string
            enum:
              - asc
              - desc
          description: Sort direction.
        - in: query
          name: relationship
          schema:
            type: string
            enum:
              - all
          description: Set to `all` to include relationship data (affiliates, offers, creative).
      requestBody:
        required: true
        content:
          application/json:
            example:
              filters:
                custom_setting_status: "active"
              search_terms:
                - search_type: "name"
                  value: "holiday"
            schema:
              type: object
              properties:
                filters:
                  type: object
                  properties:
                    network_offer_ids:
                      type: array
                      items:
                        type: integer
                      description: Filter by offer IDs.
                    network_affiliate_ids:
                      type: array
                      items:
                        type: integer
                      description: Filter by affiliate IDs.
                    custom_setting_status:
                      type: string
                      enum:
                        - active
                        - inactive
                      description: Filter by setting status.
                search_terms:
                  type: array
                  description: Array of search filters to apply.
                  items:
                    type: object
                    required:
                      - search_type
                      - value
                    properties:
                      search_type:
                        type: string
                        enum:
                          - name
                          - offer
                          - affiliate
                        description: The field to search on.
                      value:
                        type: string
                        description: The search value.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  custom_creative_settings:
                    type: array
                    items:
                      type: object
                      properties:
                        network_custom_creative_setting_id:
                          type: integer
                          description: Unique custom creative setting ID.
                        network_id:
                          type: integer
                          description: Network ID.
                        network_offer_creative_id:
                          type: integer
                          description: ID of the associated offer creative.
                        network_offer_ids:
                          type: array
                          items:
                            type: integer
                          description: List of associated offer IDs.
                        network_affiliate_ids:
                          type: array
                          items:
                            type: integer
                          description: List of affiliate IDs this setting applies to.
                        name:
                          type: string
                          description: Custom creative setting name.
                        custom_setting_status:
                          type: string
                          enum:
                            - active
                            - inactive
                          description: Setting status.
                        time_created:
                          type: integer
                          example: 1734455015
                          description: Unix timestamp of creation.
                        time_saved:
                          type: integer
                          example: 1734455015
                          description: Unix timestamp of last update.
                        optimized_thumbnail_url:
                          type: string
                          description: URL to the optimized thumbnail.
                        relationship:
                          type: object
                          description: Included when `relationship=all` is passed.
                          properties:
                            affiliates:
                              type: array
                              items:
                                type: object
                              description: Associated affiliate details.
                            offers:
                              type: array
                              items:
                                type: object
                              description: Associated offer details.
                            creative:
                              type: object
                              description: Associated creative details.
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                      page_size:
                        type: integer
                      total_count:
                        type: integer
      security:
        - API Key: []
  /networks/custom/creative:
    get:
      summary: List Custom Creative Settings
      tags:
        - Custom Creative Settings
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  custom_creative_settings:
                    type: array
                    items:
                      $ref: "#/components/schemas/CustomCreativeSetting"
      security:
        - API Key: []
    post:
      summary: Create Custom Creative Setting
      tags:
        - Custom Creative Settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomCreativeSettingInput"
            example:
              network_offer_creative_ids: []
              network_affiliate_ids:
                - 7
              name: "Custom Creative Setting"
              custom_setting_status: "active"
              creative:
                network_offer_id: 1
                name: "Banner Ad 300x250"
                creative_type: "html"
                is_private: false
                creative_status: "active"
                html_code: "<div>Ad content</div>"
                width: 300
                height: 250
                additional_offer_ids: []
                is_apply_specific_affiliates: false
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomCreativeSetting"
      security:
        - API Key: []
    patch:
      summary: Bulk Update Custom Creative Status
      tags:
        - Custom Creative Settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkStatusUpdateRequest"
            example:
              custom_creative_setting_ids: [1, 2, 3]
              status: "inactive"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
      security:
        - API Key: []
  /networks/custom/creative/{settingId}:
    get:
      summary: Get Custom Creative Setting by ID
      tags:
        - Custom Creative Settings
      parameters:
        - in: path
          name: settingId
          required: true
          schema:
            type: integer
          description: The custom creative setting identifier.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomCreativeSetting"
      security:
        - API Key: []
    put:
      summary: Update Custom Creative Setting
      description: >
        Update an existing custom creative setting. All fields must be
        provided in the request body.
      tags:
        - Custom Creative Settings
      parameters:
        - in: path
          name: settingId
          required: true
          schema:
            type: integer
          description: The custom creative setting identifier.
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_offer_creative_ids: [10, 20]
              network_affiliate_ids: [100, 200]
              name: "Updated Holiday Banner"
              custom_setting_status: "active"
              creative:
                network_id: 1
                network_offer_id: 5
                name: "Updated Banner Creative"
                creative_type: "html"
                is_private: false
                creative_status: "active"
                html_code: "<div>Updated ad content</div>"
                width: 300
                height: 250
                additional_offer_ids: []
                is_apply_specific_affiliates: false
            schema:
              $ref: "#/components/schemas/CustomCreativeSettingInput"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomCreativeSetting"
      security:
        - API Key: []
    delete:
      summary: Delete Custom Creative Setting
      tags:
        - Custom Creative Settings
      parameters:
        - in: path
          name: settingId
          required: true
          schema:
            type: integer
          description: The custom creative setting identifier.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
      security:
        - API Key: []
components:
  schemas:
    CustomCreativeSetting:
      type: object
      properties:
        network_custom_creative_setting_id:
          type: integer
          description: Unique custom creative setting ID.
        network_id:
          type: integer
          description: Network ID.
        network_offer_creative_ids:
          type: array
          items:
            type: integer
          description: List of offer creative IDs assigned.
        network_affiliate_ids:
          type: array
          items:
            type: integer
          description: List of affiliate IDs this setting applies to.
        name:
          type: string
          description: Custom creative setting name.
        custom_setting_status:
          type: string
          enum:
            - active
            - inactive
          description: Setting status.
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of creation.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of last update.
        relationship:
          type: object
          properties:
            affiliates:
              type: array
              items:
                type: object
              description: Associated affiliate details.
            creative:
              type: object
              description: Associated creative details.
    CustomCreativeSettingInput:
      type: object
      required:
        - network_affiliate_ids
        - name
        - custom_setting_status
        - creative
      properties:
        network_offer_creative_ids:
          type: array
          items:
            type: integer
          description: List of offer creative IDs to assign. When a `creative` object is provided, the newly created creative's ID will replace the values in this array.
        network_affiliate_ids:
          type: array
          items:
            type: integer
          description: List of affiliate IDs this setting applies to.
        name:
          type: string
          description: Custom creative setting name.
        custom_setting_status:
          type: string
          enum:
            - active
            - inactive
          description: Setting status.
        creative:
          type: object
          description: Creative object to create inline. A new creative is always created from this object.
          required:
            - network_offer_id
            - name
            - creative_type
            - is_private
            - creative_status
          properties:
            network_offer_id:
              type: integer
              description: Offer ID for the new creative.
            name:
              type: string
              description: Creative name.
            creative_type:
              type: string
              enum:
                - image
                - html
                - thumbnail
                - email
                - archive
                - video
                - text
                - link
              description: Creative type.
            is_private:
              type: boolean
              description: Whether the creative is private.
            creative_status:
              type: string
              enum:
                - active
                - paused
                - deleted
              description: Creative status.
            html_code:
              type: string
              description: HTML code (required if type is html or email).
            width:
              type: integer
              description: Width in pixels (required if type is html).
            height:
              type: integer
              description: Height in pixels (required if type is html).
            email_from:
              type: string
              description: Sender email (required if type is email).
            email_subject:
              type: string
              description: Email subject (required if type is email).
            additional_offer_ids:
              type: array
              items:
                type: integer
              description: Additional offer IDs to associate.
            is_apply_specific_affiliates:
              type: boolean
              description: Apply to specific affiliates only.
            resource_file:
              type: object
              properties:
                temp_url:
                  type: string
                  description: Temporary URL of the uploaded file.
                original_file_name:
                  type: string
                  description: Original file name.
            html_files:
              type: array
              items:
                type: object
              description: HTML files for archive creatives.
            html_assets:
              type: array
              items:
                type: object
              description: HTML assets for archive creatives.
    BulkStatusUpdateRequest:
      type: object
      required:
        - custom_creative_setting_ids
        - status
      properties:
        custom_creative_setting_ids:
          type: array
          items:
            type: integer
          description: List of custom creative setting IDs to update.
        status:
          type: string
          enum:
            - active
            - inactive
          description: New status for all specified settings.
  securitySchemes:
    API Key:
      description: The Everflow API key generated from the Control Center > Security.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey