Skai (Kenshoo) Jobs API

openapi: 3.2.0
info:
  title: Skai Jobs 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: Jobs
  description: 'Operations that can take more than a few seconds are defined as **jobs**.

    Initiating such operations will return a _job_id_, which can then be used to query the status of the job, and once completed to query the job results.'
paths:
  /api/v1/jobs/{job_id}/results/file:
    get:
      tags:
      - Jobs
      summary: Job results
      operationId: getJobResults
      parameters:
      - $ref: '#/components/parameters/ks'
      - name: job_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: info_level
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
          enum:
          - SUMMARY
          - BREAKDOWN
      responses:
        200:
          description: OK
          content:
            multipart/form-data:
              schema:
                type: string
                description: The job result in file form.
                format: binary
              example: '<a file with results will be returned here.

                See relevant examples in the documentation of each bulk operation>'
        404:
          description: NOT FOUND
          content:
            application/json:
              schema:
                type: string
                description: There are no results when the info level SUMMARY and job ID c42f1168-4cd6-42e8-b654-2a7f0043699e are selected.
                example: There are no results when the info level SUMMARY and job ID c42f1168-4cd6-42e8-b654-2a7f0043699e are selected.
        500:
          $ref: '#/components/responses/InternalServerError'
  /api/v1/jobs/{job_id}/status:
    get:
      tags:
      - Jobs
      summary: Job status
      operationId: getJobStatus
      parameters:
      - $ref: '#/components/parameters/ks'
      - name: job_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: string
                description: The status of the Skai job.
                enum:
                - JOB_PENDING
                - JOB_RUNNING
                - JOB_COMPLETED
                - JOB_COMPLETED_WITH_FAILURES
        404:
          description: NOT FOUND
          content:
            application/json:
              schema:
                type: string
                description: Job ID not found
              example: Job ID not found
        500:
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          items:
            $ref: '#/components/schemas/EntityResponse'
    EntityResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
        success:
          type: boolean
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorField'
    ApiResponseStatus:
      type: string
      readOnly: true
      enum:
      - SUCCESS
      - FAILED
      - PARTIAL_SUCCESS
    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
  responses:
    ApiResponse:
      $ref: '#/components/schemas/ApiResponse'
    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: {}
  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