openapi: 3.0.3
info:
  title: Everflow Network API - Creatives
  description: >
    Endpoints for managing creatives in the Everflow network.
    For more on creative types, see the [Creatives guide](https://helpdesk.everflow.io/customer/simple-creatives-images-links-videos-others).
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Creatives
paths:
  /networks/creativestable:
    post:
      summary: Find Creatives (Advanced)
      tags:
        - Creatives
      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.
      requestBody:
        required: true
        content:
          application/json:
            example:
              search_terms:
                - search_type: "creative_status"
                  value: "active"
            schema:
              type: object
              properties:
                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
                          - creative_status
                          - creative_type
                          - network_offer_name
                          - network_offer_id
                        description: The field to search on.
                      value:
                        type: string
                        description: The search value.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  creatives:
                    type: array
                    items:
                      type: object
                      properties:
                        network_offer_creative_id:
                          type: integer
                          description: Unique creative ID.
                        network_id:
                          type: integer
                          description: Network ID.
                        name:
                          type: string
                          description: Name of the creative.
                        network_offer_id:
                          type: integer
                          description: Associated offer ID.
                        network_offer_name:
                          type: string
                          description: Associated offer name.
                        creative_type:
                          type: string
                          enum:
                            - image
                            - html
                            - thumbnail
                            - email
                            - archive
                            - video
                            - text
                            - link
                          description: >
                            Type of the creative. Can be one of: image, html,
                            thumbnail, email, archive, video, text, or link.
                        is_private:
                          type: boolean
                          description: Whether the creative is accessible by all affiliates.
                        creative_status:
                          type: string
                          enum:
                            - active
                            - paused
                            - deleted
                          description: Status of the creative. Can be active, paused, or deleted.
                        resource_url:
                          type: string
                          description: URL to the creative resource file.
                        html_code:
                          type: string
                          description: HTML content of the creative. Present when creative_type is `html`, `email`, or `link`.
                        width:
                          type: integer
                          description: Width of the creative in pixels.
                        height:
                          type: integer
                          description: Height of the creative in pixels.
                        email_from:
                          type: string
                          description: Content of the From field of the email.
                        email_subject:
                          type: string
                          description: Content of the Subject field of the email.
                        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.
                        email_subject_lines:
                          type: string
                          description: Additional email subject lines for the creative.
                        email_from_lines:
                          type: string
                          description: Additional email from lines for the creative.
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                      page_size:
                        type: integer
                      total_count:
                        type: integer
      security:
        - API Key: []
  /networks/creatives/{creativeId}:
    get:
      summary: Get Creative by ID
      tags:
        - Creatives
      parameters:
        - in: path
          name: creativeId
          required: true
          schema:
            type: integer
          description: The creative ID.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Creative"
      security:
        - API Key: []
    put:
      summary: Update Creative
      tags:
        - Creatives
      parameters:
        - in: path
          name: creativeId
          required: true
          schema:
            type: integer
          description: The creative ID.
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_offer_id: 1
              name: "Banner Ad 300x250"
              creative_type: "html"
              html_code: "<div>Ad content</div>"
              creative_status: "active"
              width: 300
              height: 250
            schema:
              $ref: "#/components/schemas/CreativeInput"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Creative"
      security:
        - API Key: []
  /networks/creatives:
    get:
      summary: List All Creatives
      description: >
        Retrieve all creatives without pagination or table search.
        For filtered and paginated results, use the List Creatives endpoint.
      tags:
        - Creatives
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Creative"
      security:
        - API Key: []
    post:
      summary: Create Creative
      tags:
        - Creatives
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_offer_id: 1
              name: "Banner Ad 300x250"
              creative_type: "html"
              html_code: "<div>Ad content</div>"
              creative_status: "active"
              width: 300
              height: 250
            schema:
              $ref: "#/components/schemas/CreativeInput"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Creative"
      security:
        - API Key: []
  /networks/patch/offers/creative/apply:
    patch:
      summary: Bulk Edit Creatives
      tags:
        - Creatives
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_offer_creative_ids: [10, 11, 12]
              fields:
                - field_type: "creative_status"
                  field_value: "paused"
                  operator: "overwrite"
            schema:
              type: object
              required:
                - network_offer_creative_ids
                - fields
              properties:
                network_offer_creative_ids:
                  type: array
                  items:
                    type: integer
                  description: Array of creative IDs to modify.
                fields:
                  type: array
                  description: Array of field modifications to apply.
                  items:
                    type: object
                    required:
                      - field_type
                      - field_value
                      - operator
                    properties:
                      field_type:
                        type: string
                        enum:
                          - name
                          - is_private
                          - creative_status
                        description: The field to modify.
                      field_value:
                        description: The value to set (type varies by field).
                      operator:
                        type: string
                        enum:
                          - overwrite
                          - append
                          - clear
                          - delete
                        description: The operation to perform.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                    description: Whether the bulk edit was successful.
      security:
        - API Key: []
components:
  schemas:
    Creative:
      type: object
      properties:
        network_offer_creative_id:
          type: integer
          description: Unique creative ID.
        network_id:
          type: integer
          description: Network ID.
        network_offer_id:
          type: integer
          description: Associated offer ID.
        name:
          type: string
          description: Name of the creative.
        creative_type:
          type: string
          enum:
            - image
            - html
            - thumbnail
            - email
            - archive
            - video
            - text
            - link
          description: >
            Type of the creative. Can be one of: image, html, thumbnail, email,
            archive, video, text, or link.
        is_private:
          type: boolean
          description: Whether the creative is accessible by all affiliates.
        creative_status:
          type: string
          enum:
            - active
            - paused
            - deleted
          description: Status of the creative. Can be active, paused, or deleted.
        resource_url:
          type: string
          description: URL to the creative resource file.
        html_code:
          type: string
          description: HTML content of the creative. Present when creative_type is `html`, `email`, or `link`.
        width:
          type: integer
          description: Width of the creative in pixels.
        height:
          type: integer
          description: Height of the creative in pixels.
        email_from:
          type: string
          description: Content of the From field of the email.
        email_subject:
          type: string
          description: Content of the Subject field of the email.
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of creation.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of last update.
        additional_offer_ids:
          type: array
          items:
            type: integer
          nullable: true
          description: IDs of all additional offers linked to this creative.
        is_apply_specific_affiliates:
          type: boolean
          description: Whether the creative is restricted to specific affiliates.
        email_subject_lines:
          type: string
          description: Additional email subject lines for the creative.
        email_from_lines:
          type: string
          description: Additional email from lines for the creative.
        relationship:
          type: object
          properties:
            offer:
              type: object
              properties:
                network_offer_id:
                  type: integer
                network_id:
                  type: integer
                network_advertiser_id:
                  type: integer
                network_offer_group_id:
                  type: integer
                name:
                  type: string
                offer_status:
                  type: string
                network_tracking_domain_id:
                  type: integer
                visibility:
                  type: string
                currency_id:
                  type: string
            resource_asset:
              type: object
              properties:
                network_asset_id:
                  type: integer
                content_type:
                  type: string
                filename:
                  type: string
                url:
                  type: string
                file_size:
                  type: integer
                image_width:
                  type: integer
                image_height:
                  type: integer
    CreativeInput:
      type: object
      required:
        - network_offer_id
        - name
        - creative_type
        - creative_status
        - is_private
        - additional_offer_ids
        - is_apply_specific_affiliates
      properties:
        network_offer_id:
          type: integer
          description: The ID of the offer this creative belongs to. Only required when creating a new creative on its own (not part of an offer creation).
        name:
          type: string
          description: Name of the creative.
        creative_type:
          type: string
          enum:
            - image
            - html
            - thumbnail
            - email
            - archive
            - video
            - text
            - link
          description: >
            Type of the creative. Can be one of: image, html, thumbnail, email,
            archive, video, text, or link.
        is_private:
          type: boolean
          description: Whether the creative is accessible by all affiliates.
        creative_status:
          type: string
          enum:
            - active
            - paused
            - deleted
          description: Status of the creative. Can be active, paused, or deleted.
        html_code:
          type: string
          description: HTML content of the creative. Required only if creative_type is `html`, `email`, or `link`.
        width:
          type: integer
          description: Width of the creative. Required only if creative_type is html.
        height:
          type: integer
          description: Height of the creative. Required only if creative_type is html.
        email_from:
          type: string
          description: Content of the From field of the email. Required only if creative_type is email.
        email_subject:
          type: string
          description: Content of the Subject field of the email. Required only if creative_type is email.
        email_from_lines:
          type: string
          description: >
            Newline-delimited list of From lines. Supersedes `email_from` when sent.
            Omit the field to fall back to `email_from`. Send an empty string to
            clear all From lines.
        email_subject_lines:
          type: string
          description: >
            Newline-delimited list of subject lines. Supersedes `email_subject` when
            sent. Omit the field to fall back to `email_subject`. Send an empty
            string to clear all subject lines.
        additional_offer_ids:
          type: array
          items:
            type: integer
          description: IDs of all additional offers linked to this creative.
        is_apply_specific_affiliates:
          type: boolean
          description: Whether to restrict the creative to specific affiliates. Defaults to `false`.
        resource_file:
          type: object
          description: >
            Content of the creative. Should only be included if creative_type is
            image, thumbnail, archive, or video.
          required:
            - temp_url
            - original_file_name
          properties:
            temp_url:
              type: string
              description: Temporary URL of the file, obtained by uploading the file through the API.
            original_file_name:
              type: string
              description: Original name of the file.
        html_files:
          type: array
          description: >
            List of files attached to the creative. Should only be included if
            creative_type is html or email.
          items:
            type: object
            required:
              - temp_url
              - original_file_name
            properties:
              temp_url:
                type: string
                description: Temporary URL of the file, obtained by uploading the file through the API.
              original_file_name:
                type: string
                description: >
                  Name of the file, which will be used to generate the file macro.
                  For example, "Example File Name" will produce the macro {{example_file_name}}.
        html_assets:
          type: array
          description: >
            Array of asset objects associated with the creative. Used for html
            and email creative types.
          items:
            type: object
            required:
              - content_type
              - filename
              - url
              - file_size
              - image_width
              - image_height
            properties:
              content_type:
                type: string
                description: MIME type of the asset (e.g. image/png, image/gif).
              filename:
                type: string
                description: Name of the asset file.
              url:
                type: string
                description: URL of the asset file, obtained by uploading the file through the API.
              file_size:
                type: integer
                description: Size of the file in bytes.
              image_width:
                type: integer
                description: Width of the image asset in pixels. Required only if the asset is an image.
              image_height:
                type: integer
                description: Height of the image asset in pixels. Required only if the asset is an image.
  securitySchemes:
    API Key:
      description: The Everflow API key generated from the Control Center > Security.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey