Skai (Kenshoo)

Skai (Kenshoo) Meta Ads API

Manage dimension tags on Meta ads. > **Scope:** This section covers applying and removing Skai dimension labels on Meta ads. Publishers: Meta

GitHub OpenAPI
Business capability
Digital Marketing Management BC-400.60

Operations 5

GET /api/v2/ads Get Ads #
PUT /api/v2/ads Edit an existing ad #
POST /api/v2/ads Create a new ad #
GET /api/v1/ads/tags Get Ads tags #
PUT /api/v1/ads/tags Edit Ad tags #

Documentation

📖
Documentation
https://developers.skai.io/
📖
APIReference
https://developers.kenshoo.com/
📖
GettingStarted
https://developers.skai.io/#section/Authentication
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/skai-kenshoo/refs/heads/main/authentication/skai-kenshoo-authentication.yml
📖
RateLimits
https://raw.githubusercontent.com/api-evangelist/skai-kenshoo/refs/heads/main/rate-limits/skai-kenshoo-rate-limits.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/skai-kenshoo/refs/heads/main/openapi/skai-kenshoo-meta-ads-api-openapi.yml

Other Resources

🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/skai-kenshoo/refs/heads/main/conventions/skai-kenshoo-conventions.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/skai-kenshoo/refs/heads/main/errors/skai-kenshoo-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/skai-kenshoo/refs/heads/main/data-model/skai-kenshoo-data-model.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/skai-kenshoo-meta-ads-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

skai-kenshoo-meta-ads-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Skai Meta Ads 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 Ads
  description: 'Manage dimension tags on Meta ads.


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


    Publishers:

    Meta'
paths:
  /api/v2/ads:
    get:
      tags:
      - Meta Ads
      summary: Get Ads
      description: 'Get ads API call allows you to retrieve ad information.

        The result is a list of ad 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/adIds'
      - $ref: '#/components/parameters/limit'
      responses:
        200:
          $ref: '#/components/responses/getFacebookAdEntitySuccessResponse'
        400:
          $ref: '#/components/responses/getAdBadRequest'
      operationId: getApiV2Ads
      x-operation-id-source: derived
    put:
      tags:
      - Meta Ads
      summary: Edit an existing ad
      parameters:
      - $ref: '#/components/parameters/ksV2'
      requestBody:
        $ref: '#/components/requestBodies/editFacebookAd'
      responses:
        200:
          $ref: '#/components/responses/EntitySuccessResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
      operationId: putApiV2Ads
      x-operation-id-source: derived
    post:
      tags:
      - Meta Ads
      summary: Create a new ad
      parameters:
      - $ref: '#/components/parameters/ksV2'
      requestBody:
        $ref: '#/components/requestBodies/createFacebookAd'
      responses:
        201:
          $ref: '#/components/responses/EntitySuccessResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
      operationId: postApiV2Ads
      x-operation-id-source: derived
  /api/v1/ads/tags:
    get:
      tags:
      - Meta Ads
      summary: Get Ads tags
      description: 'Get ad tags API call allows you to retrieve a tags assigned to ad.

        The result is a list of Ad tags assignment objects that can be paged through using the returned next_page/previous_page values.'
      operationId: getAdsTags
      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 Ads
      summary: Edit Ad tags
      operationId: updateAdsTags
      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:
    adDTO:
      type: object
      properties:
        ad_group_id:
          type: integer
          description: Skai ID of the ad group
        name:
          type: string
          description: Ad name
        status:
          type: string
          description: Status
          enum:
          - ACTIVE
          - PAUSED
        bid:
          oneOf:
          - $ref: '#/components/schemas/facebookAdBid'
        creative:
          oneOf:
          - $ref: '#/components/schemas/facebookAdCreativeDTO'
        tracking:
          oneOf:
          - $ref: '#/components/schemas/facebookAdTracking'
      description: The properties for the newly created ad
      example:
      - name: New Ad
        ad_group_id: 12345
        status: ACTIVE
        bid:
          bid_amount: 23.05
        creative:
          ad_type: PAGE_POST
          post_type: LINK
          post_text: ad body
          description: ad description
          headline: ad headline
          call_to_action: DOWNLOAD
          link: skai.io
          caption: skai.io
          image_name: theBestImage
          page_id: 21
          instagram_actor_id: 33
        tracking:
          pixel_ids:
          - 4308
          use_kenshoo_tracking: true
    facebookEditAdCreative:
      type: object
      properties:
        post_text:
          type: string
          description: Post text
        description:
          type: string
          description: Description
        headline:
          type: string
          description: Headline
        call_to_action:
          oneOf:
          - $ref: '#/components/schemas/facebookAdCallToAction'
        link:
          type: string
          description: Destination URL
        caption:
          type: string
          description: Display link
        image_name:
          type: string
          description: Image name
        video_name:
          type: string
          description: Video name
        video_thumbnail_name:
          type: string
          description: Video thumbnail name
        page_id:
          type: integer
          description: Page id
        instagram_actor_id:
          type: integer
          description: Instagram actor id
      description: Ad creative
    facebookAdCallToAction:
      type: string
      description: Call to action
      enum:
      - BOOK_TRAVEL
      - LISTEN_MUSIC
      - OPEN_LINK
      - PLAY_GAME
      - SHOP_NOW
      - USE_APP
      - WATCH_VIDEO
      - INSTALL_MOBILE_APP
      - INSTALL_APP
      - LEARN_MORE
      - SIGN_UP
      - DOWNLOAD
      - USE_MOBILE_APP
      - WATCH_MORE
      - CONTACT_US
      - GET_QUOTE
      - SUBSCRIBE
      - SELL_NOW
      - APPLY_NOW
      - DONATE_NOW
      - VOTE_NOW
      - LIKE_PAGE
      - NO_BUTTON
      - CALL_NOW
      - BUY_NOW
      - GET_OFFER
      - GET_OFFER_VIEW
      - GET_DIRECTIONS
      - MESSAGE_PAGE
      - RECORD_NOW
      - OPEN_MOVIES
      - EVENT_RSVP
      - CALL
      - SEE_MENU
      - MESSAGE_USER
      - REGISTER_NOW
      - REQUEST_TIME
      - SAVE
      - ORDER_NOW
      - GET_SHOWTIMES
      - VIEW_INSTAGRAM_PROFILE
      - LISTEN_NOW
      - BUY_TICKETS
      - WHATSAPP_MESSAGE
      - SEARCH
      - PAY_TO_ACCESS
      - INSTAGRAM_MESSAGE
      - START_ORDER
      - TRY_IN_CAMERA
    createFacebookAd:
      required:
      - ad_group_id
      - bid
      - creative
      - name
      - status
      type: object
      properties:
        ad_group_id:
          type: integer
          description: Skai ID of the ad group
        name:
          type: string
          description: Ad name
        status:
          type: string
          description: Status
          enum:
          - ACTIVE
          - PAUSED
        bid:
          oneOf:
          - $ref: '#/components/schemas/facebookAdBid'
        creative:
          oneOf:
          - $ref: '#/components/schemas/facebookAdCreative'
        tracking:
          oneOf:
          - $ref: '#/components/schemas/facebookAdTracking'
      description: The properties for the newly created ad
      example:
      - name: New Ad
        ad_group_id: 12345
        status: ACTIVE
        bid:
          bid_amount: 23.05
        creative:
          ad_type: PAGE_POST
          post_type: LINK
          post_text: ad body
          description: ad description
          headline: ad headline
          call_to_action: DOWNLOAD
          link: skai.io
          caption: skai.io
          image_name: theBestImage
          video_name: theBestVideo
          video_thumbnail_name: theBestThumbnail
          page_id: 21
          instagram_actor_id: 33
        tracking:
          pixel_ids:
          - 4308
          use_kenshoo_tracking: true
    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
    facebookAdDTO:
      type: object
      properties:
        id:
          type: integer
          description: Skai ID of the ad
        ad_group_id:
          type: integer
          description: Skai ID of the ad group
        name:
          type: string
          description: Ad name
        status:
          type: string
          description: Status
          enum:
          - ACTIVE
          - PAUSED
        bid:
          oneOf:
          - $ref: '#/components/schemas/facebookAdBid'
        creative:
          oneOf:
          - $ref: '#/components/schemas/facebookAdCreativeDTO'
        tracking:
          oneOf:
          - $ref: '#/components/schemas/facebookAdTracking'
    facebookAdCreative:
      required:
      - ad_type
      - instagram_actor_id
      - link
      - page_id
      - post_type
      type: object
      properties:
        ad_type:
          oneOf:
          - $ref: '#/components/schemas/facebookAdType'
        post_type:
          oneOf:
          - $ref: '#/components/schemas/facebookAdPostType'
        post_text:
          type: string
          description: Post text
        description:
          type: string
          description: Description
        headline:
          type: string
          description: Headline
        call_to_action:
          description: Required when post_type is VIDEO.
          oneOf:
          - $ref: '#/components/schemas/facebookAdCallToAction'
        link:
          type: string
          description: Destination URL
        caption:
          type: string
          description: Display link
        image_name:
          type: string
          description: Image name
        video_name:
          type: string
          description: Video name. Required when post_type is VIDEO.
        video_thumbnail_name:
          type: string
          description: Video thumbnail name. Optional; if omitted no thumbnail is set.
        page_id:
          type: integer
          description: Page id
        instagram_actor_id:
          type: integer
          description: Instagram actor id
      description: Ad creative
    facebookAdPostType:
      type: string
      description: Ad post type
      enum:
      - LINK
      - VIDEO
    EntityResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
        success:
          type: boolean
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorField'
    facebookAdCreativeDTO:
      type: object
      properties:
        ad_type:
          oneOf:
          - $ref: '#/components/schemas/facebookAdType'
        post_type:
          oneOf:
          - $ref: '#/components/schemas/facebookAdPostType'
        post_text:
          type: string
          description: Post text
        description:
          type: string
          description: Description
        headline:
          type: string
          description: Headline
        call_to_action:
          oneOf:
          - $ref: '#/components/schemas/facebookAdCallToAction'
        link:
          type: string
          description: Destination URL
        caption:
          type: string
          description: Display link
        image_name:
          type: string
          description: Image name
        video_name:
          type: string
          description: Video name
        video_thumbnail_name:
          type: string
          description: Video thumbnail name
        page_id:
          type: integer
          description: Page id
        instagram_actor_id:
          type: integer
          description: Instagram actor id
      description: Ad creative
    getAdApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/adDTO'
        paging:
          $ref: '#/components/schemas/Paging'
        error_message:
          type: string
          readOnly: true
    facebookAdBid:
      type: object
      properties:
        bid_amount:
          type: number
          description: Bid amount
      description: Bid
    editFacebookAd:
      required:
      - id
      type: object
      properties:
        id:
          type: integer
          description: Skai ID of the ad
        name:
          type: string
          description: Ad name
        status:
          type: string
          description: Status
          enum:
          - ACTIVE
          - PAUSED
          - ARCHIVED
        bid:
          oneOf:
          - $ref: '#/components/schemas/facebookAdBid'
        creative:
          oneOf:
          - $ref: '#/components/schemas/facebookEditAdCreative'
        tracking:
          oneOf:
          - $ref: '#/components/schemas/facebookAdTracking'
      description: The properties for edited ad
      example:
      - id: 1234
        name: New Ad name
        status: PAUSED
        bid:
          bid_amount: 3.14
        creative:
          post_text: new ad body
          description: new ad description
          headline: new ad headline
          call_to_action: CALL_NOW
          link: kenshoo.com
          caption: kenshoo.com
          image_name: betterImage
          video_name: betterVideo
          video_thumbnail_name: betterThumbnail
          page_id: 12
          instagram_actor_id: 77
        tracking:
          pixel_ids:
          - 450
          use_kenshoo_tracking: false
    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
    operationType:
      type: string
      description: Operation type
      enum:
      - ATTACH
      - DETACH
    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
    getFacebookAdApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/facebookAdDTO'
        paging:
          $ref: '#/components/schemas/Paging'
        error_message:
          type: string
          readOnly: true
    ApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          items:
            $ref: '#/components/schemas/EntityResponse'
    facebookAdTracking:
      type: object
      properties:
        pixel_ids:
          type: array
          description: Facebook pixel ids
          items:
            type: integer
        use_kenshoo_tracking:
          type: boolean
          description: Use kenshoo tracking
      description: Tracking
    Paging:
      type: object
      properties:
        previous_page:
          type: string
          readOnly: true
        next_page:
          type: string
          readOnly: true
    facebookAdType:
      type: string
      description: Ad type
      enum:
      - PAGE_POST
    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
    adIds:
      name: ids
      in: query
      description: 'Filter by ad ID.

        Returns ad whose 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
    getAdBadRequest:
      description: Bad request (usually indicates validation failure for client input)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getAdApiResponse'
          example:
            status: FAILED
            entities: []
            paging: null
            error_message: The value in page_id is invalid
    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'
    getFacebookAdEntitySuccessResponse:
      description: The operation was completed successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getFacebookAdApiResponse'
          example:
          - status: SUCCESS
            entities:
            - id: 1234
              name: New Ad
              ad_group_id: 12345
              status: ACTIVE
              bid:
                bid_amount: 23.05
              creative:
                ad_type: PAGE_POST
                post_type: LINK
                post_text: ad body
                description: ad description
                headline: ad headline
                call_to_action: DOWNLOAD
                link: skai.io
                caption: skai.io
                image_name: theBestImage
                video_name: theBestVideo
                page_id: 21
                instagram_actor_id: 33
              tracking:
                pixel_ids:
                - 4308
                use_kenshoo_tracking: true
            paging:
              previous_page: null
              next_page: MQ==
            error_message: null
    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
    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:
    createFacebookAd:
      description: The ad details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/createFacebookAd'
      required: true
    editEntityTagsRequest:
      description: The entity tags edit request details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/editEntityTagsRequest'
      required: true
    editFacebookAd:
      description: The ad details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/editFacebookAd'
      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