Skai (Kenshoo) Campaigns API

openapi: 3.2.0
info:
  title: Skai 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: Campaigns
  description: 'Create, update, and retrieve campaigns.


    > **Scope:** This API covers common campaign attributes — name, budget, bid, status, dates, and campaign type.

    > For the full range of campaign settings (targeting, extensions, dimension labels, and publisher-specific fields)

    > use Bulk Update (One File), which handles millions of rows across all non-Meta publishers.


    Publishers:

    Search

    Social (excl. Meta)

    Retail Media'
paths:
  /api/v1/campaigns:
    get:
      tags:
      - Campaigns
      summary: Get campaigns
      description: 'Get campaigns API call allows you to retrieve campaign information. You can filter by multiple fields, such as the profile ID and channel type, or request specific campaigns by their IDs.

        The result is a list of campaign objects that can be paged through using the returned next_page/previous_page values.'
      operationId: getCampaigns
      parameters:
      - $ref: '#/components/parameters/ks'
      - $ref: '#/components/parameters/pageId'
      - $ref: '#/components/parameters/campaignIds'
      - $ref: '#/components/parameters/channelCampaignIds'
      - $ref: '#/components/parameters/profileId'
      - $ref: '#/components/parameters/channelTypes'
      - $ref: '#/components/parameters/campaignStatuses'
      responses:
        200:
          $ref: '#/components/responses/GetCampaignEntitySuccessResponse'
        400:
          $ref: '#/components/responses/GetCampaignBadRequest'
    put:
      tags:
      - Campaigns
      summary: Edit an existing campaign
      description: 'Update one or more campaigns. Editable attributes are documented in the request body schema below.


        **Need more attributes?** Use Bulk Update (One File) for bulk edits with the full attribute set.'
      operationId: updateCampaigns
      parameters:
      - $ref: '#/components/parameters/ks'
      requestBody:
        $ref: '#/components/requestBodies/editCampaigns'
      responses:
        200:
          $ref: '#/components/responses/EntitySuccessResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Campaigns
      summary: Create a new campaign
      description: 'Create one or more campaigns. Supported attributes are documented in the request body schema below (name, budget, bid, status, dates, campaign type).


        **Need more attributes?** Use Bulk Update (One File) to create campaigns with the full range of settings including targeting, extensions, dimension labels, and publisher-specific fields.'
      operationId: createCampaigns
      parameters:
      - $ref: '#/components/parameters/ks'
      requestBody:
        $ref: '#/components/requestBodies/createCampaigns'
      responses:
        201:
          $ref: '#/components/responses/EntitySuccessResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    editCampaign:
      required:
      - id
      type: object
      properties:
        id:
          type: integer
          description: Skai ID of the campaign
        channel_account_id:
          type: integer
          description: Skai ID of the publisher account
        campaign_name:
          type: string
          description: Campaign name
        budget:
          type: number
          description: Campaign budget in the profile's currency
        budget_type:
          type: string
          description: Budget type
          enum:
          - DEFAULT
          - DAILY_FOR_ADGROUP
          - MONTHLY_FOR_CAMPAIGN
          - LIFETIME
        search_bid:
          type: number
          description: Default search bid in the profile's currency
        content_bid:
          type: number
          description: Default content bid in the profile's currency
        status:
          type: string
          description: Campaign status
          enum:
          - ACTIVE
          - PAUSED
          - DELETED
          - REVIEW
        order_line:
          type: string
          description: Order line of the campaign
        start_date:
          type: string
          description: Campaign start date. If specified, must be in the future.
          format: yyyy-MM-dd
        end_date:
          type: string
          description: Campaign end date. If specified, must be in the future and later than the campaign start date.
          format: yyyy-MM-dd
        tracking_level:
          type: string
          description: Campaign tracking level
          enum:
          - NONE
          - PROFILE_DEFAULT
          - CAMPAIGN
          - ADS
          - KEYWORDS
          - ADS_AND_KEYWORDS
        shopping_settings:
          $ref: '#/components/schemas/shoppingSettings'
        default_geographical_targeting:
          type: string
          description: Geographical targeting inheritance options
          enum:
          - INHERIT_FROM_PROFILE
          - ENTIRE_WORLD
      description: The properties for the updated campaign
      example:
        channel_account_id: '14411'
        campaign_name: Edit Campaign
        budget: '153000.0'
        search_bid: '1.0'
        content_bid: '1.0'
        start_date: '2026-01-01'
        end_date: '3000-09-28'
        campaign_type: SHOPPING_STANDARD
        shopping_settings:
          merchant_id: '8740'
          sales_country: US
          priority: LOW
    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
    shoppingSettings:
      type: object
      properties:
        merchant_id:
          type: number
          description: Merchant center account ID
        sales_country:
          type: string
          description: Country of sale for the shopping campaign
        priority:
          type: string
          description: Priority of the shopping campaign
          enum:
          - LOW
          - MEDIUM
          - HIGH
          - SMART_SHOPPING_CAMPAIGN
      description: Campaign shopping settings
    EntityResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
        success:
          type: boolean
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorField'
    GetCampaignApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/CampaignDTO'
        paging:
          $ref: '#/components/schemas/Paging'
        error_message:
          type: string
          readOnly: true
    createCampaign:
      required:
      - campaign_name
      - channel_account_id
      type: object
      properties:
        channel_account_id:
          type: integer
          description: Skai ID of the publisher account
        campaign_name:
          type: string
          description: Campaign name
        budget:
          type: number
          description: Campaign budget in the profile's currency
        budget_type:
          type: string
          description: Budget type
          enum:
          - DEFAULT
          - DAILY_FOR_ADGROUP
          - MONTHLY_FOR_CAMPAIGN
          - LIFETIME
        search_bid:
          type: number
          description: Default search bid in the profile's currency
        content_bid:
          type: number
          description: Default content bid in the profile's currency
        status:
          type: string
          description: Campaign status
          enum:
          - ACTIVE
          - PAUSED
          - DELETED
          - REVIEW
          default: ACTIVE
        order_line:
          type: string
          description: Order line of the campaign
        start_date:
          type: string
          description: Campaign start date. If not specified, will start immediately. If specified, must be in the future.
          format: yyyy-MM-dd
        end_date:
          type: string
          description: Campaign end date. If specified, must be in the future and later than the campaign start date.
          format: yyyy-MM-dd
        tracking_level:
          type: string
          description: Campaign tracking level
          enum:
          - NONE
          - PROFILE_DEFAULT
          - CAMPAIGN
          - ADS
          - KEYWORDS
          - ADS_AND_KEYWORDS
          default: PROFILE_DEFAULT
        campaign_type:
          type: string
          description: Campaign type
          enum:
          - TEXT_CAMPAIGN
          - SMART_SHOPPING
          - SHOPPING_STANDARD
          default: TEXT_CAMPAIGN
        shopping_settings:
          $ref: '#/components/schemas/shoppingSettings'
        default_geographical_targeting:
          type: string
          description: Geographical targeting inheritance options
          enum:
          - INHERIT_FROM_PROFILE
          - ENTIRE_WORLD
          default: INHERIT_FROM_PROFILE
      description: The properties for the created campaign
      example:
        channel_account_id: '14411'
        campaign_name: New Campaign
        budget: '153000.0'
        search_bid: '1.0'
        content_bid: '1.0'
        start_date: '2026-01-01'
        end_date: '3000-09-28'
        campaign_type: SHOPPING_STANDARD
        shopping_settings:
          merchant_id: '8740'
          sales_country: US
          priority: LOW
    CampaignDTO:
      type: object
      properties:
        id:
          type: integer
          description: Skai ID of the campaign
        channel_campaign_id:
          type: string
          description: Publisher ID of the campaign
        channel_account_id:
          type: integer
          description: Skai ID of the publisher account
        profile_id:
          type: integer
          description: Skai ID of the profile
        channel_type:
          type: string
          description: Campaign channel type
          enum:
          - Google
          - Microsoft
          - Universal
          - Yandex
          - Baidu
          - YahooJapan
          - YahooGemini
          - Pinterest
          - Amazon
          - Facebook
          - Walmart
        campaign_name:
          type: string
          description: Campaign name
        budget:
          type: number
          description: Campaign budget in the profile's currency
        budget_type:
          type: string
          description: Budget type
          enum:
          - DEFAULT
          - DAILY_FOR_ADGROUP
          - MONTHLY_FOR_CAMPAIGN
          - LIFETIME
        search_bid:
          type: number
          description: Default search bid in the profile's currency
        content_bid:
          type: number
          description: Default content bid in the profile's currency
        status:
          type: string
          description: Campaign status
          enum:
          - ACTIVE
          - PAUSED
          - DELETED
          - REVIEW
          default: ACTIVE
        order_line:
          type: string
          description: Order line of the campaign
        start_date:
          type: string
          description: Campaign start date
          format: yyyy-MM-dd
        end_date:
          type: string
          description: Campaign end date
          format: yyyy-MM-dd
        tracking_level:
          type: string
          description: Campaign tracking level
          enum:
          - NONE
          - PROFILE_DEFAULT
          - CAMPAIGN
          - ADS
          - KEYWORDS
          - ADS_AND_KEYWORDS
          default: PROFILE_DEFAULT
        campaign_type:
          type: string
          description: Campaign type
          enum:
          - TEXT_CAMPAIGN
          - SMART_SHOPPING
          - SHOPPING_STANDARD
          default: TEXT_CAMPAIGN
        shopping_settings:
          $ref: '#/components/schemas/shoppingSettings'
    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
  parameters:
    profileId:
      name: profile_id
      in: query
      description: 'Filter by profile ID.

        Returns the campaigns whose profile ID equals your profile ID.

        '
      required: false
      style: form
      explode: true
      schema:
        type: string
    ks:
      name: ks
      in: query
      description: The KS to refer the request to. You can find this ID in the Skai platform under _Administration_ -> _About Skai_ -> _Server ID_
      required: true
      style: form
      explode: true
      schema:
        type: string
      example: '1234'
    channelTypes:
      name: channel_types
      in: query
      description: 'Filter by channel type.

        Returns the campaigns whose channel types are included in the list.

        '
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          enum:
          - Google
          - Microsoft
          - Universal
          - Yandex
          - Baidu
          - YahooJapan
          - YahooGemini
          - Pinterest
          - Amazon
          - Facebook
          - Walmart
    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==
    channelCampaignIds:
      name: channel_campaign_ids
      in: query
      description: 'Filter by channel campaign ID.

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

        '
      required: false
      style: form
      explode: true
      schema:
        maxItems: 500
        type: array
        items:
          type: string
    campaignStatuses:
      name: statuses
      in: query
      description: 'Filter by status.

        Returns campaigns whose statuses are included in the list.

        '
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          enum:
          - Active
          - Approved
          - Paused
          - Deleted
          - Failed
          - Review
          - ToPause
          - ToDelete
          - FailedToPause
          - FailedToDelete
          - Unknown
          - Scheduled
          - Expired
          - Pending
          - Suspended
          - PausedBudgetDepleted
  requestBodies:
    createCampaigns:
      description: The campaigns to create
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/createCampaign'
      required: true
    editCampaigns:
      description: The campaigns to update
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/editCampaign'
      required: true
  responses:
    GetCampaignEntitySuccessResponse:
      description: The operation was completed successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetCampaignApiResponse'
          example:
            status: SUCCESS
            entities:
            - id: 18204
              channel_campaign_id: '7247592'
              profile_id: 96
              channel_account_id: 718
              channel_type: Google
              campaign_name: name
              budget: 1000.0
              budget_type: DEFAULT
              search_bid: 0.0
              content_bid: 0.0
              status: DELETED
              order_line: null
              start_date: '2026-01-01'
              end_date: '9999-12-31'
              tracking_level: KEYWORDS
              campaign_type: null
              shopping_settings: {}
            paging:
              previous_page: null
              next_page: MQ==
            error_message: null
    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'
    GetCampaignBadRequest:
      description: Bad request (usually indicates validation failure for client input)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetCampaignApiResponse'
          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: {}
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