# Skai (Kenshoo)

> Skai (formerly Kenshoo) is an AI-powered commerce media platform for brands and agencies. It
> centralizes retail media, paid search and paid social data across 120+ publishers — Amazon
> Ads, Google Ads, Microsoft Ads, Meta, Walmart, Instacart, Kroger, Target, Pinterest, TikTok
> and more — then plans, activates, optimizes and measures campaigns from one place. Skai ships
> a REST API and first-party hosted MCP servers over the same data core.

Generated by API Evangelist (https://apievangelist.com) on 2026-08-12 from Skai's own public
surface. This is a third-party profile, not a Skai document. No Skai /llms.txt is published:
https://skai.io/llms.txt returns 410 and https://developers.skai.io/llms.txt returns 404.

## Contract at a glance

- Protocol: REST over HTTPS, JSON. OpenAPI 3.0.0, 117 paths, 158 operations, 155 schemas.
- API host: https://services.kenshoo.com (NOT api.kenshoo.com, which 404s on every path).
- Versioning: URI path. /api/v1 for almost everything; /api/v2 for Meta entities and the
  second-generation incrementality data-source endpoints.
- Auth: `Authorization: Bearer <access_token>`, a JWT obtained by exchanging a permanent
  refresh token. NOT OAuth 2.0 on the REST side.
- Tenancy: a `ks` query parameter (the Skai account/server ID, e.g. ks1234) is required on 51
  operations. Multi-agency users pin `agency_id` when minting a token.
- Rate limit: 60 requests/minute and 2,000 requests/hour PER USER. 429 on exhaustion.
- Errors: Skai's own envelope, not RFC 9457.
- No webhooks, no idempotency keys, no SDKs.

## Machine-readable specs

- OpenAPI (verbatim, as served): https://api-gateway-documentation-production.s3.amazonaws.com/api-gateway/docs
- OpenAPI (this repo): openapi/skai-kenshoo-api-openapi.yml
- OAuth 2.0 Authorization Server Metadata (RFC 8414): https://login.kenshoo.com/.well-known/oauth-authorization-server
- OAuth 2.0 Protected Resource Metadata (RFC 9728): https://mcp.kenshoo.com/.well-known/oauth-protected-resource
- No AsyncAPI, no GraphQL, no gRPC/protobuf, no A2A agent card.

## Getting a token

1. Once, per API user: log in at https://login.kenshoo.com/api/dev/refresh-token to get a
   permanent refresh token and a client ID. The user's role determines the token's
   permissions; Standard role or higher is required. Skai recommends a dedicated service user.
2. Per session: POST form-encoded `refresh_token`, `client_id` (and `agency_id` if the user
   belongs to several agencies) to https://services.kenshoo.com/api/v1/token. The response
   carries `access_token` and `expires_in` (typically 21600 seconds).
3. Per call: send `Authorization: Bearer <access_token>`.

Reuse the access token until `expires_in` elapses. Minting tokens too often trips the rate
limit. Detect expiry from `expires_in` or from a 401.

## Choosing the right operation

- Pull performance data, metrics or any reportable field -> `fetchReport`
  (POST /api/v1/reports) for small results, or `asyncAnalysisReport`
  (POST /api/v1/reports/async/analysis) for anything over a few thousand rows.
- Discover which columns/metrics exist -> `getAvailableColumns`
  (GET /api/v1/reports/{entity}/available_columns) or `getRelevantColumns`
  (POST /api/v1/relevant-columns).
- Change campaigns, keywords, bids, budgets or targeting AT SCALE -> `bulkUpdate`
  (POST /api/v1/bulk_update). Millions of rows, hundreds of attributes, all publishers except
  Meta. This is where full attribute coverage lives.
- Create/update a handful of entities with common attributes only -> `createCampaigns` /
  `updateCampaigns` / `createAdGroups` / `updateAdGroups` / `createAds`.
- Manage Meta (Facebook/Instagram) -> the /api/v2 endpoints and the dimension-tag operations
  (`getCampaignTags`, `updateCampaignTags`, `getAdGroupTags`, `updateAdGroupTags`,
  `getAdsTags`, `updateAdsTags`). Meta has its own schema branch and does not share
  CampaignDTO.
- Use Skai from an AI assistant -> the MCP servers below.

## Reporting semantics

`breakdown_type` controls shape:
- FLAT — unsegmented, no grouping.
- GROUP — segment by the columns in `group_bys` (e.g. {name: Day, group: TimeSegment}). Entity
  detail is dropped.
- SEGMENT — segment by date AND another column: date column in `group_bys`, extra column in
  `fields`.

Reportable entities: CAMPAIGN, ADGROUP, KEYWORD, AD, PRODUCT_ASSET, PRODUCT_TARGETING,
PORTFOLIO. KEYWORD, PRODUCT_ASSET and PRODUCT_TARGETING are reportable and bulk-updatable but
have no dedicated CRUD operations.

Skai's own guidance: filter to non-zero metrics (impressions > 0) to shrink results; scope
structure reports with a "last updated" filter; use async for large datasets.

## Long-running work

Any operation that can exceed a few seconds returns a job_id or execution_id. There are NO
webhooks and no callbacks — poll.

- Bulk: `getJobStatus` (GET /api/v1/jobs/{job_id}/status) then `getJobResults`
  (GET /api/v1/jobs/{job_id}/results/file).
- Reports: `getAsyncReportStatus` (GET /api/v1/reports/async/{execution_id}/status) then
  `downloadAsyncReport` (GET /api/v1/reports/async/{execution_id}), which returns a zip.
- Alternatively set `useOriginalDeliveryMethod=true` to deliver the report to its configured
  destination (email or FTP).

## MCP servers

Skai runs first-party hosted, remote MCP servers. Live tools/list is auth-gated (401).

- Reporting MCP — https://mcp.kenshoo.com/reports-mcp (tenant form
  https://mcp.kenshoo.com/reports-mcp/ks1234). Read-only. Published tools: `fetch_report`,
  `relevant_columns`, `get_today`, `get_change_log`, `get_competitive_context`.
- Operations MCP — https://mcp.kenshoo.com/operations-mcp. Write access for bid, budget and
  status changes at scale, with preview and approval. Skai publishes no tool names for it.

Auth: OAuth 2.0 against https://login.kenshoo.com (authorization_code + PKCE S256; scopes
openid, profile, email, offline_access), or a 90-day Personal Access Token sent as
`Authorization: Bearer <PAT>` with a `ks-name` header. ChatGPT supports OAuth only.
Setup guide: https://skai-mcp-guide.vercel.app/

`get_change_log` and `get_competitive_context` have NO REST equivalent — they exist only on
the MCP surface.

## Error handling

Errors are application/json in Skai's envelope:

    {"status":"FAILED","entities":[{"id":null,"success":false,
     "errors":[{"field_name":"name","error":"ILLEGAL_NAME"}]}]}

`status` is SUCCESS, FAILED or PARTIAL_SUCCESS. HTTP 207 Multi-Status appears on bulk Amazon
DSP endpoints — inspect `entities[].success` individually. 401 means an expired token: re-mint
and retry. Skai publishes no error-code registry, so the failure space cannot be enumerated in
advance. Watch out: the ErrorField schema names the field `fieldName` while every published
example emits `field_name`.

## Sharp edges an agent should know

- No idempotency mechanism of any kind. Retrying a `bulkUpdate` or any 207-returning call may
  re-apply changes that already succeeded. Treat writes as non-replayable.
- 429 is documented in prose but declared on ZERO operations. Handle it anyway.
- Rate-limit response headers exist but Skai does not name them, and there is no Retry-After.
- No request-id/correlation header.
- Cursor pagination (`page_id` + `limit`, cursors in `paging.next_page`/`previous_page`) is
  declared on only 9 of 158 operations. Elsewhere, filter arrays cap at 500 items.
- 29 operations declare an unexplained HTTP 300 with no payload description.
- Four paths embed a raw regex segment — /api/v1/homepage/([0-9]+)/budget_oversight — which is
  not a valid OpenAPI path template.
- Several operations have no operationId, so they cannot be reliably code-generated or bound
  to a tool.
- No deprecation policy and no Sunset header. POST /api/v1/reports/async is deprecated in its
  summary text only; use POST /api/v1/reports/async/analysis.

## Commercial

- Pricing (published list prices, priced on annual ad spend managed): https://skai.io/pricing/
  Standard $114k/yr (up to $4M spend), Advanced $276k/yr (up to $10M), Enterprise $504k/yr (up
  to $20M), Enterprise Premier $756k/yr (up to $35M), Enterprise Premier + contact us.
- No free tier, no trial, no self-serve signup. API and MCP access is included with the
  platform subscription; there is no metered API pricing.

## Links

- Developer hub: https://developers.skai.io/ (also https://developers.kenshoo.com/)
- Website: https://skai.io/
- Status: https://status.skai.io/
- Blog: https://skai.io/blog/
- GitHub: https://github.com/kenshoo
- Security & privacy center: https://skai.io/skai-information-security-and-privacy-center/
  (ISO/IEC 27001:2013, SOC 2 Type 2, ISO 9001:2015; responsible disclosure)
- Login: https://app.kenshoo.com/portal
- Terms: https://skai.io/legal/ · Privacy: https://skai.io/privacy-policy/

## Not available

No changelog or release-notes page. No public roadmap. No SLA. No Postman collection. No
sandbox or test-mode credentials. No CLI. No client SDK in any language — the only first-party
npm packages are @kenshooui React UI components, last released 2021. No webhooks, no AsyncAPI,
no GraphQL, no gRPC. No A2A agent card. No security.txt.