> ## 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 theme={null}
https://api.criteo.com/<version>/retail-media/{endpoint}
```

## Request `type`

In request payloads, `type` identifies the resource type you are sending. For requests, `type` is completely optional. You can omit it, but it can be useful in complex systems where you validate payload structure and data types before sending data to Criteo's API.

The technical definition of each resource type is contained in the machine-readable [OpenAPI specification](/criteo-apis/docs/criteo-api-swagger).

### Example

```json theme={null}
{
  "data": [
    {
      "type": "AudienceSegment",
      "attributes": {
        "name": "{segmentName}",
        "description": "{segmentDescription}",
        "retailerId": "{retailerId}",
        "contactList": {
          "identifierType": "Email"
        }
      }
    }
  ]
}
```

***

## 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](/criteo-apis/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)

***