> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Pattern

# Base URL

```http URL theme={null}
https://api.criteo.com/<version>/retail-media/{endpoint}
```

***

# Synchronous Endpoints

All campaign operations except for Catalogs are achieved through synchronous endpoints. Those will return a response in real-time.

<table>
  <thead>
    <tr>
      <th>
        <p>
          Operation
        </p>
      </th>

      <th>
        <p>
          Method
        </p>
      </th>

      <th>
        <p>
          Endpoint
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            Create an entity
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            POST
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            /\{plural-parent-entity-name}/\{parentEntityId}/\{plural-entity-name}
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            Delete from a list
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            POST
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            /\{plural-parent-entity-name}/\{parentEntityId}/\{plural-entity-name}/delete
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            Append to a list
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            POST
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            /\{plural-parent-entity-name}/\{parentEntityId}/\{plural-entity-name}/append
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            Get all entities
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            GET
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            /\{plural-parent-entity-name}/\{parentEntityId}/\{plural-entity-name}
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            Get a specific entity
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            GET
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            /\{plural-entity-name}/\{entityId}
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            Update a specific entity
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            PUT
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            /\{plural-entity-name}/\{entityId}
          </code>
        </p>
      </td>
    </tr>
  </tbody>
</table>

<Info>
  * "Create" operations using the `POST` method expect every **Required (R)** field; omitting **Optional (O)** fields will set those fields to **Default** values.\* "Update" operations using the `PUT` method expect every **Write (W)** field; omitting these fields is equivalent to setting them to `null`, if possible.
</Info>

***

# Asynchronous Endpoints

"Catalogs" and "Reports" are requested and retrieved through asynchronous endpoints. Those will send a response once the request is done processing (not in real-time).

<table>
  <thead>
    <tr>
      <th>
        <p>
          Operation
        </p>
      </th>

      <th>
        <p>
          Method
        </p>
      </th>

      <th>
        <p>
          Endpoint
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            Create a resource request
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            POST
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            /\{plural-parent-entity-name}/\{parentEntityId}/\{plural-entity-name}
          </code>
        </p>

        <p>
          or
        </p>

        <p>
          <code>
            /\{plural-parent-entity-name}/\{plural-entity-name}
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            Retrieve the status of the requested resource
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            GET
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            /\{plural-entity-name}/\{entityId}/status
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            Retrieve the output of the requested resource
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            GET
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            /\{plural-entity-name}/\{entityId}/output
          </code>
        </p>
      </td>
    </tr>
  </tbody>
</table>

***

# Bulk calls

<Info>
  Please refer to[ this page](/retail-media/docs/bulk-calls) for more information about Bulk Calls.
</Info>

***

# Error Codes

When sending more than 50 IDs, you will get the following `400 Bad request` HTTP Response:

```json theme={null}
{
    "errors": [
        {
            "code": "exceeded-ids-cap",
            "title": "Requests are capped for 50 unique ids, 51 were provided",
            "type": "validation",
            "traceId": "aa47dd83-8ca9-4a79-a179-ad5be6932ff1",
            "instance": "/api/v1/reports/line-item",
            "detail": "ids Requests are capped for 50 unique ids, 51 were provided (Value: \"1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51\")",
            "source": {
                "ids": "data/attributes/ids"
            }
        }
    ]
}
```

This Contains:

* Error code: `exceeded-ids-cap`

* Error title: `Requests are capped for 50 unique ids, {count of ids requested} were provided`

* Error Type: `validation`

* A traceId: `aa47dd83-8ca9-4a79-a179-ad5be6932ff1`

* Instance: the report requested (here `/api/v1/reports/line-item`)

* Detail: Title with a list of requested IDs

* Source: The parameter that caused the error (IDs in this case)

## What's next

* [Bulk Calls](/retail-media/v2025.07/docs/bulk-calls)
* [Campaign Structure](/retail-media/v2025.07/docs/campaign-structure)
* [List of Endpoints](/retail-media/v2025.07/docs/list-of-endpoints-including-preferred-deals)
* [Rate Limits](/retail-media/v2025.07/docs/rate-limits)
* [Statuses](/retail-media/v2024.10/docs/status)