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

# Response & Error Format

> The response envelope, list/filter pattern, and status codes shared across Prizm API endpoints.

<script type="application/ld+json">
  {`{
            "@context": "https://schema.org",
            "@type": "TechArticle",
            "headline": "Response & Error Format",
            "description": "The response envelope, list/filter pattern, and status codes shared across Prizm API endpoints.",
            "url": "https://docs.dqlabs.ai/api-reference/response-format",
            "publisher": {
              "@type": "Organization",
              "name": "DQLabs Inc",
              "logo": "https://media.brand.dev/332adc35-5bc4-4d2b-bf78-256aa4a5e414.svg"
            }
            }`}
</script>

<Note>
  This page documents what's confirmed from the current API collection. The `data` field's contents are still being documented per endpoint — see the note in [API Overview](/api-reference/overview).
</Note>

## Response envelope

Every endpoint returns the same top-level shape (confirmed from a live capture against `GET /api/v1/core/asset/{assetId}`):

```json theme={null}
{
  "success": true,
  "message": "Retrieved successfully",
  "timestamp": "2026-09-21T09:43:50.316067+00:00",
  "correlation_id": "1bff0823-3db2-4b12-bf56-22ea8d38bba2",
  "data": { }
}
```

| Field            | Type              | Description                                                                                                                                                                                  |
| :--------------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `success`        | boolean           | Whether the request completed successfully                                                                                                                                                   |
| `message`        | string            | Human-readable description of the result                                                                                                                                                     |
| `timestamp`      | string (ISO 8601) | Server time the response was generated                                                                                                                                                       |
| `correlation_id` | string (UUID)     | Unique ID for this request — include it when contacting support about a specific call                                                                                                        |
| `data`           | object            | The endpoint's actual payload — shape varies per endpoint. Confirmed field-by-field for endpoints marked so on their reference page; other endpoints still show a placeholder until captured |

<Note>
  `timestamp` and `correlation_id` were confirmed on one endpoint (`GET /api/v1/core/asset/{assetId}`) and are assumed to be a shared response-wrapper convention across the API. That assumption will be confirmed or corrected as more endpoints are captured.
</Note>

## List, filter, sort, and search

Endpoints that return a collection (typically named `.../list`) accept a consistent request body rather than query parameters:

```json theme={null}
{
  "pagination": { "page": 1, "pageSize": 10 },
  "sorting": [],
  "filters": [],
  "search": "",
  "export": false
}
```

| Field                 | Type    | Description                                       |
| :-------------------- | :------ | :------------------------------------------------ |
| `pagination.page`     | integer | Page number, starting at 1                        |
| `pagination.pageSize` | integer | Records per page                                  |
| `sorting`             | array   | Sort instructions — shape pending documentation   |
| `filters`             | array   | Filter instructions — shape pending documentation |
| `search`              | string  | Free-text search term                             |
| `export`              | boolean | Whether the response is intended for export       |

## Paginated list responses

For collection endpoints (`.../list`), `data` itself wraps the array plus pagination metadata — confirmed across 30+ live `list` endpoints:

```json theme={null}
{
  "success": true,
  "message": "Retrieved successfully",
  "timestamp": "...",
  "correlation_id": "...",
  "data": {
    "data": [ { "...": "..." } ],
    "total_count": 214,
    "metrics": { }
  }
}
```

| Field              | Type    | Description                                                                                    |
| :----------------- | :------ | :--------------------------------------------------------------------------------------------- |
| `data.data`        | array   | The actual records for this page                                                               |
| `data.total_count` | integer | Total records matching the filter, across all pages                                            |
| `data.metrics`     | object  | Present on most list endpoints; aggregate stats for the collection — shape varies per resource |

<Note>
  Some collection endpoints (`GET /api/v1/integration`, `GET /api/v1/notification/list`'s sibling `GET /api/v1/notification`) return the array directly as `data`, without the `data.data` wrapper. Check the specific endpoint's reference page for which shape it uses.
</Note>

## Status codes

| Code  | Meaning                                                                                                                                                                                                                                    |
| :---- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | Request succeeded                                                                                                                                                                                                                          |
| `401` | Missing, invalid, or expired bearer token — see [Authentication](/api-reference/authentication)                                                                                                                                            |
| `404` | Resource not found (for example, an unknown `{id}` in the path)                                                                                                                                                                            |
| `422` | Request validation failed — observed on a few endpoints that require specific body fields beyond the generic list/filter pattern (for example date ranges on log endpoints). Exact required fields per endpoint are still being confirmed. |

<Note>
  A couple of endpoints in the source collection redirect (`307`) to a trailing-slash form of the same path, and one documented as `POST` (`/api/v1/governance/field-property`) returned `405 Method Not Allowed` live against both spellings. `POST /api/v1/governance/product/{productId}/output-port` returned `500` against a real product ID during capture. These look like small inconsistencies or bugs between the Postman collection and the live API — noted here rather than silently corrected or hidden, since they haven't been confirmed with the API owners yet.
</Note>

<Note>
  This list covers the status codes confirmed so far. A complete error code reference — including validation error shapes for `400`-class responses — is pending and will be added once available.
</Note>