openapi: 3.1.0
info:
  title: Criteo Retail Media API
  description: |
    Criteo Retail Media programmatic API for campaign management, audiences,
    line items, products, keywords, balances, catalogs, categories and
    reporting. Endpoint inventory drawn from https://developers.criteo.com.
  version: "2026-01"
  contact:
    name: Criteo Developers
    url: https://developers.criteo.com
servers:
  - url: https://api.criteo.com
    description: Production
components:
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.criteo.com/oauth2/token
          scopes: {}
        authorizationCode:
          authorizationUrl: https://consent.criteo.com/authorize
          tokenUrl: https://api.criteo.com/oauth2/token
          scopes: {}
security:
  - OAuth2ClientCredentials: []
paths:
  /oauth2/token:
    post:
      summary: Generate access token
      operationId: getToken
      tags: [Authentication]
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type: { type: string }
                client_id: { type: string }
                client_secret: { type: string }
      responses:
        "200": { description: Token }
  /2026-01/retail-media/accounts:
    get:
      summary: List accessible accounts
      operationId: getAccounts
      tags: [Accounts]
      responses:
        "200": { description: Accounts }
  /2026-01/retail-media/accounts/{accountId}:
    get:
      summary: Get account by id
      operationId: getAccount
      tags: [Accounts]
      parameters:
        - in: path
          name: accountId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Account }
  /2026-01/retail-media/account-management/accounts/{accountId}/brands/add:
    post:
      summary: Add brands to account
      operationId: addBrandsToAccount
      tags: [Accounts]
      parameters:
        - in: path
          name: accountId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Brands added }
  /2026-01/retail-media/account-management/accounts/{accountId}/brands/remove:
    post:
      summary: Remove brands from account
      operationId: removeBrandsFromAccount
      tags: [Accounts]
      parameters:
        - in: path
          name: accountId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Brands removed }
  /2026-01/retail-media/accounts/{accountId}/campaigns:
    get:
      summary: List campaigns by account
      operationId: getCampaignsByAccount
      tags: [Campaigns]
      parameters:
        - in: path
          name: accountId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Campaigns }
    post:
      summary: Create campaign
      operationId: createCampaign
      tags: [Campaigns]
      parameters:
        - in: path
          name: accountId
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "201": { description: Created }
  /2026-01/retail-media/campaigns/{campaignId}:
    get:
      summary: Get campaign
      operationId: getCampaign
      tags: [Campaigns]
      parameters:
        - in: path
          name: campaignId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Campaign }
    patch:
      summary: Update campaign
      operationId: updateCampaign
      tags: [Campaigns]
      parameters:
        - in: path
          name: campaignId
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "200": { description: Updated }
  /2026-01/retail-media/campaigns/{campaignId}/preferred-line-items:
    get:
      summary: List preferred line items
      operationId: getPreferredLineItems
      tags: [LineItems]
      parameters:
        - in: path
          name: campaignId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Preferred line items }
    post:
      summary: Create preferred line item
      operationId: createPreferredLineItem
      tags: [LineItems]
      parameters:
        - in: path
          name: campaignId
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "201": { description: Created }
  /2026-01/retail-media/campaigns/{campaignId}/auction-line-items:
    get:
      summary: List auction line items
      operationId: getAuctionLineItems
      tags: [LineItems]
      parameters:
        - in: path
          name: campaignId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Auction line items }
    post:
      summary: Create auction line item
      operationId: createAuctionLineItem
      tags: [LineItems]
      parameters:
        - in: path
          name: campaignId
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "201": { description: Created }
  /2026-01/retail-media/line-items/{lineItemId}:
    get:
      summary: Get line item
      operationId: getLineItem
      tags: [LineItems]
      parameters:
        - in: path
          name: lineItemId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Line item }
    patch:
      summary: Update line item
      operationId: updateLineItem
      tags: [LineItems]
      parameters:
        - in: path
          name: lineItemId
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "200": { description: Updated }
  /2026-01/retail-media/line-items/{lineItemId}/products:
    get:
      summary: List promoted products
      operationId: getPromotedProducts
      tags: [Products]
      parameters:
        - in: path
          name: lineItemId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Products }
  /2026-01/retail-media/line-items/{lineItemId}/products/append:
    post:
      summary: Add promoted products
      operationId: addPromotedProducts
      tags: [Products]
      parameters:
        - in: path
          name: lineItemId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Added }
  /2026-01/retail-media/line-items/{lineItemId}/products/delete:
    delete:
      summary: Remove promoted products
      operationId: removePromotedProducts
      tags: [Products]
      parameters:
        - in: path
          name: lineItemId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Removed }
  /2026-01/retail-media/line-items/{lineItemId}/keywords:
    get:
      summary: List keywords
      operationId: getKeywords
      tags: [Keywords]
      parameters:
        - in: path
          name: lineItemId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Keywords }
  /2026-01/retail-media/line-items/{lineItemId}/keywords/add-remove:
    post:
      summary: Add/remove keywords in bulk
      operationId: bulkKeywords
      tags: [Keywords]
      parameters:
        - in: path
          name: lineItemId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Updated }
  /2026-01/retail-media/accounts/{accountId}/balances:
    get:
      summary: List balances
      operationId: getBalances
      tags: [Balances]
      parameters:
        - in: path
          name: accountId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Balances }
    post:
      summary: Create balance
      operationId: createBalance
      tags: [Balances]
      parameters:
        - in: path
          name: accountId
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "201": { description: Created }
  /2026-01/retail-media/balances/{balanceId}/campaigns:
    get:
      summary: Get campaigns by balance
      operationId: getCampaignsByBalance
      tags: [Balances]
      parameters:
        - in: path
          name: balanceId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Campaigns }
  /2026-01/retail-media/reports/campaigns:
    post:
      summary: Generate campaigns report
      operationId: createCampaignsReport
      tags: [Reports]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "200": { description: Report job }
  /2026-01/retail-media/reports/line-items:
    post:
      summary: Generate line items report
      operationId: createLineItemsReport
      tags: [Reports]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "200": { description: Report job }
  /2026-01/retail-media/reports/{reportId}/status:
    get:
      summary: Get report status
      operationId: getReportStatus
      tags: [Reports]
      parameters:
        - in: path
          name: reportId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Status }
  /2026-01/retail-media/reports/{reportId}/output:
    get:
      summary: Get report output
      operationId: getReportOutput
      tags: [Reports]
      parameters:
        - in: path
          name: reportId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Report output }
  /2026-01/retail-media/accounts/{accountId}/catalogs:
    post:
      summary: Request catalog export
      operationId: createCatalog
      tags: [Catalogs]
      parameters:
        - in: path
          name: accountId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Catalog job }
  /2026-01/retail-media/catalogs/{catalogId}/status:
    get:
      summary: Get catalog status
      operationId: getCatalogStatus
      tags: [Catalogs]
      parameters:
        - in: path
          name: catalogId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Status }
  /2026-01/retail-media/catalogs/{catalogId}/output:
    get:
      summary: Get catalog output
      operationId: getCatalogOutput
      tags: [Catalogs]
      parameters:
        - in: path
          name: catalogId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Catalog data }
  /2026-01/retail-media/categories:
    get:
      summary: Search categories
      operationId: searchCategories
      tags: [Categories]
      responses:
        "200": { description: Categories }
  /2026-01/retail-media/accounts/{accountId}/audience-segments/create:
    post:
      summary: Create audience segment
      operationId: createAudienceSegment
      tags: [Audiences]
      parameters:
        - in: path
          name: accountId
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "201": { description: Created }
  /2026-01/retail-media/accounts/{accountId}/audience-segments/search:
    get:
      summary: Search audience segments
      operationId: searchAudienceSegments
      tags: [Audiences]
      parameters:
        - in: path
          name: accountId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Segments }