Skai (Kenshoo) Meta Campaigns API

openapi: 3.2.0
info:
  title: Skai Meta Campaigns API
  description: '# Overview

    Skai APIs provide programmatic access to advertising data and campaign management across Search, Social, and Retail Media publishers.'
  version: 1.0.0
  x-logo:
    url: https://grid.kenshoo.com/resources-frontend/latest/kenshoo_logo/skai-logo-devportal.svg
    backgroundColor: '#FFFFFF'
    altText: Skai
servers:
- url: https://services.kenshoo.com
security:
- BearerAuth: []
tags:
- name: Meta Campaigns
  description: 'Manage dimension tags on Meta campaigns.


    > **Scope:** This section covers applying and removing Skai dimension labels on Meta campaigns.

    > For Meta campaign creation and full management, contact your Skai account team.


    Publishers:

    Meta'
paths:
  /api/v2/campaigns:
    get:
      tags:
      - Meta Campaigns
      summary: Get campaigns
      description: 'Get campaigns API call allows you to retrieve campaign information.

        The result is a list of campaign objects that can be paged through using the returned next_page/previous_page values.'
      parameters:
      - $ref: '#/components/parameters/ksV2'
      - $ref: '#/components/parameters/pageId'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/campaignIds'
      responses:
        200:
          $ref: '#/components/responses/getFacebookCampaignEntitySuccessResponse'
        400:
          $ref: '#/components/responses/getFacebookCampaignBadRequest'
      operationId: getApiV2Campaigns
      x-operation-id-source: derived
    put:
      tags:
      - Meta Campaigns
      summary: Edit an existing campaign
      parameters:
      - $ref: '#/components/parameters/ksV2'
      requestBody:
        $ref: '#/components/requestBodies/editFacebookCampaigns'
      responses:
        200:
          $ref: '#/components/responses/EntitySuccessResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
      operationId: putApiV2Campaigns
      x-operation-id-source: derived
    post:
      tags:
      - Meta Campaigns
      summary: Create a new campaign
      parameters:
      - $ref: '#/components/parameters/ksV2'
      requestBody:
        $ref: '#/components/requestBodies/createFacebookCampaigns'
      responses:
        201:
          $ref: '#/components/responses/EntitySuccessResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
      operationId: postApiV2Campaigns
      x-operation-id-source: derived
  /api/v1/campaigns/tags:
    get:
      tags:
      - Meta Campaigns
      summary: Get Campaigns tags
      description: 'Get campaign tags API call allows you to retrieve a tags assigned to campaign.

        The result is a list of Campaign tags assignment objects that can be paged through using the returned next_page/previous_page values.'
      operationId: getCampaignTags
      parameters:
      - $ref: '#/components/parameters/ksV2'
      - $ref: '#/components/parameters/pageId'
      - $ref: '#/components/parameters/adGroupIds'
      - $ref: '#/components/parameters/limit'
      responses:
        200:
          $ref: '#/components/responses/getEntityTagsSuccessResponse'
        400:
          $ref: '#/components/responses/getEntityTagsBadRequest'
    put:
      tags:
      - Meta Campaigns
      summary: Edit Campaign tags
      operationId: updateCampaignTags
      parameters:
      - $ref: '#/components/parameters/ksV2'
      requestBody:
        $ref: '#/components/requestBodies/editEntityTagsRequest'
      responses:
        200:
          $ref: '#/components/responses/EntitySuccessResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    facebookCampaignType:
      type: object
      properties:
        objective:
          type: string
          description: Campaign objective
          enum:
          - OUTCOME_AWARENESS
          - OUTCOME_ENGAGEMENT
          - OUTCOME_LEADS
          - OUTCOME_SALES
          - OUTCOME_TRAFFIC
          - OUTCOME_APP_PROMOTION
        buying_type:
          type: string
          description: Campaign buying type
          enum:
          - AUCTION
          - REACH_AND_FREQUENCY
        promoted_object:
          $ref: '#/components/schemas/facebookPromotedObject'
        special_ad_categories:
          type: array
          items:
            type: string
            enum:
            - NONE
            - HOUSING
            - CREDIT
            - EMPLOYMENT
            - ISSUES_ELECTIONS_POLITICS
        portfolio_id:
          type: integer
          description: Portfolio ID
      description: Campaign type
    facebookCampaignBid:
      type: object
      properties:
        strategy:
          type: string
          description: Campaign bid strategy
          enum:
          - LOWEST_COST_WITHOUT_CAP
          - LOWEST_COST_WITH_BID_CAP
          - COST_CAP
          - LOWEST_COST_WITH_MIN_ROAS
      description: Campaign bid
    tag:
      type: object
      properties:
        name:
          type: string
          description: Tag name
        category:
          type: string
          description: Category name
    ErrorField:
      type: object
      properties:
        fieldName:
          type: string
          description: The error field
        error:
          type: string
          description: Error message
        parameters:
          type: object
          additionalProperties:
            type: string
          description: Error additional properties
    facebookImpressionCaps:
      type: object
      properties:
        daily_impression_cap:
          type: integer
          description: Daily impression cap
        lifetime_impression_cap:
          type: integer
          description: Lifetime impression cap
      description: Impression caps
    facebookCampaignBudget:
      type: object
      properties:
        type:
          type: string
          description: Campaign budget type
          enum:
          - DAILY
          - LIFETIME
        budget:
          type: number
          description: Campaign budget
        spend_cap:
          type: number
          description: Campaign spend cap
        pacing_types:
          type: array
          description: Budget pacing types
          items:
            type: string
            enum:
            - STANDARD
            - NO_PACING
            - DAY_PARTING
            - DISABLED
        caps:
          oneOf:
          - $ref: '#/components/schemas/facebookImpressionCaps'
      description: Campaign budget
    EntityResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
        success:
          type: boolean
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorField'
    facebookCampaignStatus:
      type: string
      description: Campaign status
      enum:
      - ACTIVE
      - PAUSED
      - DELETED
      - ARCHIVED
      - WITH_ISSUES
      - IN_PROCESS
    facebookPromotedObject:
      type: object
      properties:
        page_id:
          type: integer
          description: Page ID
        product_catalog_id:
          type: integer
          description: Product catalog ID
      description: Promoted object
    facebookCampaign:
      type: object
      properties:
        id:
          type: integer
          description: Skai ID of the campaign
        channel_id:
          type: string
          description: Channel ID of the campaign
        account_id:
          type: integer
          description: Skai ID of the publisher account
        profile_token:
          type: string
          description: Skai profile token
        name:
          type: string
          description: Campaign name
        status:
          oneOf:
          - $ref: '#/components/schemas/facebookCampaignStatus'
        budget:
          oneOf:
          - $ref: '#/components/schemas/facebookCampaignBudget'
        bid:
          oneOf:
          - $ref: '#/components/schemas/facebookCampaignBid'
        campaign_type:
          oneOf:
          - $ref: '#/components/schemas/facebookCampaignType'
    createFacebookCampaign:
      required:
      - account_id
      - campaign_type
      - name
      - profile_token
      - status
      type: object
      properties:
        account_id:
          type: integer
          description: Skai ID of the publisher account
        profile_token:
          type: string
          description: Skai profile token
        name:
          type: string
          description: Campaign name
        status:
          oneOf:
          - $ref: '#/components/schemas/facebookCampaignStatus'
        budget:
          oneOf:
          - $ref: '#/components/schemas/facebookCampaignBudget'
        bid:
          oneOf:
          - $ref: '#/components/schemas/facebookCampaignBid'
        campaign_type:
          oneOf:
          - $ref: '#/components/schemas/facebookCampaignType'
      description: The properties for the created campaign
      example:
        status: PAUSED
        name: test name
        account_id: 234234234
        profile_token: 352ab43a-5740-11eb-ae93-0242ac130002
        campaign_type:
          objective: WEBSITE_CLICKS
          buying_type: AUCTION
        budget:
          type: LIFETIME
          budget: 100.54
    editEntityTagsRequest:
      required:
      - id
      - operation_type
      - tags
      type: object
      properties:
        id:
          type: integer
          description: Skai ID of the entity
        tags:
          type: array
          description: Tags
          items:
            $ref: '#/components/schemas/tag'
        operation_type:
          $ref: '#/components/schemas/operationType'
      description: The properties for editing entity tags
      example:
      - id: 100
        tags:
        - name: tag1
          category: cat
        - name: tag2
          category: dog
        operation_type: ATTACH
    editFacebookCampaign:
      required:
      - id
      type: object
      properties:
        id:
          type: integer
          description: Skai ID of the campaign
        name:
          type: string
          description: Campaign name
        status:
          oneOf:
          - $ref: '#/components/schemas/facebookCampaignStatus'
        budget:
          oneOf:
          - $ref: '#/components/schemas/facebookCampaignBudget'
        bid:
          oneOf:
          - $ref: '#/components/schemas/facebookCampaignBid'
        campaign_type:
          oneOf:
          - $ref: '#/components/schemas/facebookCampaignType'
      description: The properties for the updated campaign
      example:
        id: 232608652
        status: ACTIVE
        name: test name 123345
    operationType:
      type: string
      description: Operation type
      enum:
      - ATTACH
      - DETACH
    getFacebookCampaignApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/facebookCampaign'
        paging:
          $ref: '#/components/schemas/Paging'
        error_message:
          type: string
          readOnly: true
    getEntityTagsApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/getEntityTagsResponse'
        paging:
          $ref: '#/components/schemas/Paging'
        error_message:
          type: string
          readOnly: true
    ApiResponseStatus:
      type: string
      readOnly: true
      enum:
      - SUCCESS
      - FAILED
      - PARTIAL_SUCCESS
    ApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          items:
            $ref: '#/components/schemas/EntityResponse'
    Paging:
      type: object
      properties:
        previous_page:
          type: string
          readOnly: true
        next_page:
          type: string
          readOnly: true
    getEntityTagsResponse:
      type: object
      properties:
        id:
          type: integer
          description: Skai ID of the entity
        tags:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/tag'
  parameters:
    adGroupIds:
      name: ids
      in: query
      description: 'Filter by ad group ID.

        Returns ad groups whose IDs are included in your list.

        '
      required: false
      style: form
      explode: true
      schema:
        maxItems: 500
        type: array
        items:
          type: string
    campaignIds:
      name: ids
      in: query
      description: 'Filter by campaign ID.

        Returns the campaigns whose campaign IDs are included in your list.

        '
      required: false
      style: form
      explode: true
      schema:
        maxItems: 500
        type: array
        items:
          type: string
    pageId:
      name: page_id
      in: query
      description: 'Allows you to traverse pages by using the values for "next_page" and "previous_page" included under "paging" in the response.

        To return the first page, do not include page_id in the request.

        '
      required: false
      style: form
      explode: true
      schema:
        type: string
      example: Mg==
    limit:
      name: limit
      in: query
      required: false
      style: form
      explode: true
      schema:
        type: integer
        format: int32
    ksV2:
      name: ks
      in: query
      required: true
      style: form
      explode: true
      schema:
        type: string
      example: social
  responses:
    getEntityTagsSuccessResponse:
      description: The operation was completed successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getEntityTagsApiResponse'
          example:
          - id: 100
            tags:
            - name: tag1
              category: cat
            - name: tag2
              category: dog
    BadRequest:
      description: Bad request (usually indicates validation failure for client input)
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: FAILED
            entities:
            - id: null
              success: false
              errors:
              - field_name: name
                error: ILLEGAL_NAME
    EntitySuccessResponse:
      description: The entity operations succeeded
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: SUCCESS
            entities:
            - id: 1234
              success: true
              errors: []
    ApiResponse:
      $ref: '#/components/schemas/ApiResponse'
    getEntityTagsBadRequest:
      description: Bad request (usually indicates validation failure for client input)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getEntityTagsApiResponse'
          example:
            status: FAILED
            entities: []
            paging: null
            error_message: The value in page_id is invalid
    getFacebookCampaignEntitySuccessResponse:
      description: The operation was completed successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getFacebookCampaignApiResponse'
          example:
            status: SUCCESS
            entities:
            - id: 232608652
              status: ACTIVE
              budget:
                type: LIFETIME
                budget: 100.0
              name: name
              account_id: 234234234
              profile_token: 352ab43a-5740-11eb-ae93-0242ac130002
              campaign_type:
                objective: WEBSITE_CLICKS
                buying_type: AUCTION
            paging:
              previous_page: null
              next_page: ZGZjY2UyMDQtOTQyNy00MDI3LThiMjctYWUxYzk5ZjIyMTg2
            error_message: null
    getFacebookCampaignBadRequest:
      description: Bad request (usually indicates validation failure for client input)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getFacebookCampaignApiResponse'
          example:
            status: FAILED
            entities: []
            paging: null
            error_message: The value in page_id is invalid
    InternalServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: FAILED
            entities:
            - id: null
              success: false
              errors:
              - field_name: ServerError
                error: Unexpected error occurred.
                parameters: {}
  requestBodies:
    editEntityTagsRequest:
      description: The entity tags edit request details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/editEntityTagsRequest'
      required: true
    createFacebookCampaigns:
      description: The campaigns to create
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/createFacebookCampaign'
      required: true
    editFacebookCampaigns:
      description: The campaigns to update
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/editFacebookCampaign'
      required: true
x-tagGroups:
- name: Reporting
  tags:
  - Available Columns
  - Synchronous Reports
  - Asynchronous Reports
- name: Bulk Operations
  tags:
  - Jobs
  - Bulk Update
- name: AI & MCP
  tags:
  - MCP
- name: Objects
  tags:
  - Profile
  - Campaigns
  - Ad Groups
  - Ads
  - Product Groups
  - Portfolios
  - Meta Campaigns
  - Meta Ad Groups
  - Meta Ads
  - Columns