# Get objects by reference

`POST /discovery/v1/objects`

Look up objects by reference — no query, no ranking, no pagination.

Returns only the objects this channel can serve. A reference the channel
cannot serve is omitted exactly like a missing one — the two are
indistinguishable — so the result can be shorter than the request; diff it
against your own request via the ``@id`` / ``@type`` slots on each object.

## Request example

```bash
curl --request POST \
  --url 'https://api.eu1.luigisbox.ai/discovery/v1/objects?channel_id=<channel_id>' \
  --header 'x-lbx-visitor-id: <x-lbx-visitor-id>' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "references": [
    "example"
  ],
  "return_fields": [
    "example"
  ]
}'
```

## Query Parameters

| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `channel_id` | `string` | Yes | Channel identifier (serving destination). | >= 1 characters |

## Header Parameters

| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `x-lbx-visitor-id` | `string` | Yes | Stable per-browser visitor identifier, generated client-side and persisted (e.g. a UUID in localStorage or a first-party cookie). Send it whether or not personalization is on: it is what links a request to a visitor's history and to the analytics events reporting it. Keep it stable across page loads, sessions and token refreshes; never generate it server-side, or every visitor collapses into one. | >= 1 characters |

## Request Body

**Required.**

### application/json

Schema: `object`

#### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `references` | `Array<string>` | Yes | Object references in `<type>/<field>:<value>` form, for example 'product/ean:5901234123457'. | >= 1 items; <= 200 items |
| `return_fields` | `Array<string>` | No | Object fields to return; empty for the default, or ['*'] for all fields. | <= 100 items |

#### Request body example

```json
{
  "references": [
    "example"
  ],
  "return_fields": [
    "example"
  ]
}
```

## Responses

| Status | Description | Content |
|---|---|---|
| `200` | Successful Response | application/json: object |
| `400` | Malformed request | application/json: object |
| `401` | Missing or invalid credentials | application/json: object |
| `403` | Authenticated but not permitted | application/json: object |
| `404` | Resource not found | application/json: object |
| `422` | Request validation failed | application/json: object |
| `429` | Rate limit exceeded | application/json: object |
| `502` | Upstream service failed | application/json: object |

### 200

Successful Response

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `objects` | `Array<object>` | Yes | Matching objects this channel can serve.  A reference the channel cannot serve is omitted exactly like a missing one — the two are indistinguishable; callers diff against their request via ``@id`` / ``@type``. | — |
| `objects[].@id` | `string` | Yes | Unique identity of the hit. | — |
| `objects[].@type` | `string` | Yes | Type of the hit (e.g. 'product'). | — |
| `objects[].*` | `any` | No | Additional property. | — |

##### Response example

```json
{
  "objects": [
    {
      "@id": "example",
      "@type": "example"
    }
  ]
}
```

### 400

Malformed request

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 401

Missing or invalid credentials

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 403

Authenticated but not permitted

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 404

Resource not found

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 422

Request validation failed

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 429

Rate limit exceeded

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```

### 502

Upstream service failed

#### application/json

Schema: `object`

##### Attributes

| Attribute | Type | Required | Description | Constraints |
|---|---|---|---|---|
| `exception_details` | `object` | No | Machine-readable error context; empty object when there is nothing to add. | — |
| `exception_details.validation_errors` | `anyOf(Array<object>, null)` | No | Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value. | — |
| `exception_details.validation_errors[].loc` | `Array<anyOf(string, integer)>` | Yes | Path to the offending value from the request root, e.g. `["body", "filters", 0, "operator"]`. | — |
| `exception_details.validation_errors[].msg` | `string` | Yes | What is wrong with the value at `loc`. | — |
| `exception_details.validation_errors[].type` | `string` | Yes | Stable machine code for the problem, e.g. `missing` or `string_too_short`. | — |
| `exception_details.*` | `any` | No | Additional property. | — |
| `reason` | `string` | Yes | Human-readable, actionable error message. | — |
| `request_id` | `anyOf(string, null)` | No | Request correlation ID (matches the X-Request-Id response header). | — |

##### Response example

```json
{
  "exception_details": {
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}
```