openapi: 3.0.3
info:
  title: Everflow Network API - Labels
  description: >
    Endpoints for managing labels in the Everflow network. Labels are
    flexible custom tags that let everyone organize and filter data their
    own way. They can be applied to advertisers, affiliates, campaigns,
    offers, and offer groups for internal organization and searching.
    For an overview, see the [Segmentation guide](https://helpdesk.everflow.io/customer/offer-labels-categories-segmentation-options).
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Labels
paths:
  /networks/labels:
    get:
      summary: Find All
      description: >
        Retrieve all labels for the network. Returns each label name along
        with its associated ID arrays. To get the full relationship objects,
        use the Find By Label endpoint instead.
      tags:
        - Labels
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  labels:
                    type: array
                    items:
                      $ref: "#/components/schemas/LabelSummary"
              example:
                labels:
                  - label: "312312"
                    advertiser_ids: null
                    affiliate_ids: null
                    campaign_ids: null
                    offer_ids: null
                    offer_group_ids: null
                    affiliate_tier_ids: null
      security:
        - API Key: []
    post:
      summary: Create Label
      description: >
        Create a new label. A label string is required and at least one of
        the ID arrays must contain at least one entry.
      tags:
        - Labels
      requestBody:
        required: true
        content:
          application/json:
            example:
              label: "top-performer"
              advertiser_ids: [13, 26]
              affiliate_ids: [28, 35]
              affiliate_tier_ids: [3, 4]
              campaign_ids: []
              offer_group_ids: [2]
              offer_ids: [1, 8, 11]
            schema:
              $ref: "#/components/schemas/LabelInput"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                    description: Whether the operation was successful.
              example:
                result: true
      security:
        - API Key: []
    put:
      summary: Update Label
      tags:
        - Labels
      parameters:
        - in: query
          name: old_label
          required: true
          schema:
            type: string
          description: The previous label value to update.
      requestBody:
        required: true
        content:
          application/json:
            example:
              label: "top-performer-v2"
              advertiser_ids: [13, 26]
              affiliate_ids: [28, 35]
              affiliate_tier_ids: [3, 4]
              campaign_ids: []
              offer_group_ids: [2]
              offer_ids: [1, 8, 11]
            schema:
              $ref: "#/components/schemas/LabelInput"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                    description: Whether the operation was successful.
              example:
                result: true
      security:
        - API Key: []
    delete:
      summary: Delete Label
      description: >
        Delete a label by its value.
      tags:
        - Labels
      parameters:
        - in: query
          name: label
          required: true
          schema:
            type: string
          description: The label to delete.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                    description: Whether the operation was successful.
              example:
                result: true
      security:
        - API Key: []
  /networks/labels/{label}:
    get:
      summary: Find By Label
      description: >
        Retrieve a single label by its value, including the IDs and
        relationship objects for each associated resource.
      tags:
        - Labels
      parameters:
        - in: path
          name: label
          required: true
          schema:
            type: string
          description: The label to fetch.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Label"
              example:
                label: "312312"
                advertiser_ids: [26, 13]
                affiliate_ids: [35, 28]
                campaign_ids: null
                offer_ids: [1, 8, 11]
                offer_group_ids: [2]
                affiliate_tier_ids: [3, 4]
                relationship: {}
      security:
        - API Key: []
components:
  schemas:
    Label:
      type: object
      properties:
        label:
          type: string
          description: The label value.
        advertiser_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: List of advertiser IDs associated with this label.
        affiliate_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: List of affiliate IDs associated with this label.
        campaign_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: List of campaign IDs associated with this label.
        offer_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: List of offer IDs associated with this label.
        offer_group_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: List of offer group IDs associated with this label.
        affiliate_tier_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: List of affiliate tier IDs associated with this label.
        relationship:
          type: object
          description: Expanded relationship objects for each associated resource.
          properties:
            advertisers:
              type: array
              items:
                type: object
                properties:
                  network_advertiser_id:
                    type: integer
                    description: Unique advertiser ID.
                  network_id:
                    type: integer
                    description: Network ID.
                  name:
                    type: string
                    description: Advertiser name.
                  account_status:
                    type: string
                    description: Account status of the advertiser.
            affiliates:
              type: array
              items:
                type: object
                properties:
                  network_affiliate_id:
                    type: integer
                    description: Unique affiliate ID.
                  network_id:
                    type: integer
                    description: Network ID.
                  name:
                    type: string
                    description: Affiliate name.
                  account_status:
                    type: string
                    description: Account status of the affiliate.
            campaigns:
              type: array
              items:
                type: object
                properties:
                  network_campaign_id:
                    type: integer
                    description: Unique campaign ID.
                  network_id:
                    type: integer
                    description: Network ID.
                  campaign_name:
                    type: string
                    description: Campaign name.
                  campaign_status:
                    type: string
                    description: Status of the campaign.
            offers:
              type: array
              items:
                type: object
                properties:
                  network_offer_id:
                    type: integer
                    description: Unique offer ID.
                  network_id:
                    type: integer
                    description: Network ID.
                  network_advertiser_id:
                    type: integer
                    description: Advertiser ID that owns this offer.
                  network_offer_group_id:
                    type: integer
                    description: Offer group ID this offer belongs to.
                  name:
                    type: string
                    description: Offer name.
                  offer_status:
                    type: string
                    description: Status of the offer.
                  network_tracking_domain_id:
                    type: integer
                    description: Tracking domain ID used by this offer.
                  visibility:
                    type: string
                    description: Visibility setting of the offer.
                  currency_id:
                    type: string
                    description: Currency identifier for the offer.
            offer_groups:
              type: array
              items:
                type: object
                properties:
                  network_offer_group_id:
                    type: integer
                    description: Unique offer group ID.
                  network_id:
                    type: integer
                    description: Network ID.
                  network_advertiser_id:
                    type: integer
                    description: Advertiser ID that owns this offer group.
                  name:
                    type: string
                    description: Offer group name.
                  offer_group_status:
                    type: string
                    description: Status of the offer group.
                  offer_count:
                    type: integer
                    description: Number of offers in this group.
    LabelSummary:
      type: object
      properties:
        label:
          type: string
          description: The label value.
        advertiser_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: List of advertiser IDs associated with this label.
        affiliate_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: List of affiliate IDs associated with this label.
        campaign_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: List of campaign IDs associated with this label.
        offer_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: List of offer IDs associated with this label.
        offer_group_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: List of offer group IDs associated with this label.
        affiliate_tier_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: List of affiliate tier IDs associated with this label.
    LabelInput:
      type: object
      required:
        - label
      properties:
        label:
          type: string
          description: The label you want to add.
        advertiser_ids:
          type: array
          items:
            type: integer
          description: Which advertisers will have the label.
        affiliate_ids:
          type: array
          items:
            type: integer
          description: Which affiliates will have the label.
        campaign_ids:
          type: array
          items:
            type: integer
          description: Which campaigns will have the label.
        offer_ids:
          type: array
          items:
            type: integer
          description: Which offers will have the label.
        offer_group_ids:
          type: array
          items:
            type: integer
          description: Which offer groups will have the label.
        affiliate_tier_ids:
          type: array
          items:
            type: integer
          description: Which affiliate tiers will have the label.
  securitySchemes:
    API Key:
      description: The Everflow API key generated from the Control Center > Security.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey