Skai (Kenshoo) External Reports API

openapi: 3.2.0
info:
  title: Skai External Reports 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: External Reports
paths:
  /api/v1/external-reports:
    get:
      tags:
      - External Reports
      summary: Get External Score Providers
      description: 'Two variants depending on parameters provided:

        - `profileId` only → lists all ESPs for the profile (`GET /api/v1/external-reports/{profileId}`)

        - `profileId` + `espId` → returns full config for one ESP (`GET /api/v1/external-reports/config/{profileId}/{espId}`)


        Pass `espId = -1` to retrieve a blank default config (useful as a template when creating a new provider).'
      operationId: getExternalReports
      parameters:
      - $ref: '#/components/parameters/ks'
      - name: profileId
        in: query
        description: Profile ID to retrieve providers for
        required: true
        style: form
        explode: true
        schema:
          type: integer
        example: 123
      - name: espId
        in: query
        description: ESP ID to retrieve full config for. Pass -1 to get a blank default config.
        required: false
        style: form
        explode: true
        schema:
          type: integer
        example: 9
      responses:
        200:
          description: List of ESPs or full ESP config object
          content:
            application/json:
              schema:
                oneOf:
                - type: array
                  items:
                    $ref: '#/components/schemas/EspSummary'
                - $ref: '#/components/schemas/EspConfig'
              examples:
                list:
                  summary: List response
                  value:
                  - id: 9
                    name: My FTP Report
                    status: Active
                  - id: 14
                    name: Salesforce Report
                    status: Paused
        404:
          description: Profile or provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - External Reports
      summary: Update an existing ESP provider
      description: 'Replaces the full configuration of an existing ESP (`PUT /api/v1/external-reports/config/{profileId}/{espId}`).

        Provider name cannot be changed after creation. Send the complete config object — partial updates not supported (use PATCH for that).


        **Note:** GCS protocol is not supported.'
      operationId: updateExternalReport
      parameters:
      - $ref: '#/components/parameters/ks'
      - name: profileId
        in: query
        description: Profile ID the provider belongs to
        required: true
        style: form
        explode: true
        schema:
          type: integer
        example: 123
      - name: espId
        in: query
        description: ID of the ESP to update
        required: true
        style: form
        explode: true
        schema:
          type: integer
        example: 9
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EspConfig'
        required: true
      responses:
        200:
          description: Updated ESP configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EspConfig'
        400:
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        404:
          description: Provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - External Reports
      summary: Create a new ESP provider
      description: 'Creates a new External Score Provider under the given profile (`POST /api/v1/external-reports/config/{profileId}`).

        Send the full configuration in the request body. Use `GET` with `espId = -1` to get a blank config as a starting point.


        **Note:** GCS (Google Cloud Storage) protocol is not supported. Use the UI or multipart endpoint for GCS providers.'
      operationId: createExternalReport
      parameters:
      - $ref: '#/components/parameters/ks'
      - name: profileId
        in: query
        description: Profile ID to create the provider under
        required: true
        style: form
        explode: true
        schema:
          type: integer
        example: 123
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EspConfig'
        required: true
      responses:
        200:
          description: Provider created — returns new provider ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: ID of the newly created provider
              example:
                id: 42
        400:
          description: Validation failed (e.g. duplicate name, GCS protocol used)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - External Reports
      summary: Delete an ESP provider
      description: Permanently deletes an External Score Provider (`DELETE /api/v1/external-reports/{profileId}/{espId}`).
      operationId: deleteExternalReport
      parameters:
      - $ref: '#/components/parameters/ks'
      - name: profileId
        in: query
        description: Profile ID the provider belongs to
        required: true
        style: form
        explode: true
        schema:
          type: integer
        example: 123
      - name: espId
        in: query
        description: ID of the ESP to delete
        required: true
        style: form
        explode: true
        schema:
          type: integer
        example: 9
      responses:
        204:
          description: Provider deleted successfully
        404:
          description: Provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    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'
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