# Query a lookup service

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

**POST** `/lookup`

Base URL: `https://{fqdn}`

Sends a lookup request to the specified lookup service. The request body
must contain `service` (string) and `query` (any shape defined by the service).

By default the response is a `LookupAnswer` JSON object containing an array
of output records. When the `x-aggregation: yes` header is present the
response is binary (application/octet-stream): a varint-encoded outpoint
list followed by aggregated BEEF.

## Header parameters

- `x-aggregation` (string)
  When `"yes"`, return a binary aggregated BEEF payload instead of
  the default JSON LookupAnswer.

## Body

Content type: `application/json`

- `service` (string, required)
  Name of the lookup service to query (e.g. `ls_ship`).
- `query` (any, required)
  Opaque query object whose shape is defined by the lookup service.

Example:

```json
{
  "service": "string",
  "query": null
}
```

## Responses

### 200

Lookup results — JSON by default, binary when x-aggregation=yes.

- `type` ("output-list" | "freeform", required)
  `output-list` — the outputs array contains UTXO records.
  `freeform`    — the result field contains arbitrary data.
- `outputs` (object[], required)
  - `beef` (integer[], required)
    BEEF bytes encoding the transaction containing this output.
  - `outputIndex` (integer, required)
  - `context` (integer[])
    Optional opaque context bytes attached by the lookup service.
- `result` (any)
  Freeform result when type is `freeform`.

Example:

```json
{
  "type": "output-list",
  "outputs": [
    {
      "beef": [
        0
      ],
      "outputIndex": 0,
      "context": [
        0
      ]
    }
  ],
  "result": null
}
```

### 400

Bad request — validation error or missing required field.

- `status` (string, required)
- `message` (string, required)
- `code` (string)
  Stable machine-readable error code (see specs/errors.md).

Example:

```json
{
  "status": "string",
  "message": "string",
  "code": "string"
}
```

### 500

Unexpected internal error.

- `status` (string, required)
- `message` (string, required)
- `code` (string)
  Stable machine-readable error code (see specs/errors.md).

Example:

```json
{
  "status": "string",
  "message": "string",
  "code": "string"
}
```