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

# List Documents

> Retrieve all documents in a collection with optional filtering, sorting, and pagination.

## GET `/api/data/:collectionName`

Returns a list of documents from the specified collection. Supports pagination, sorting, and field-level filtering via query parameters.

<Warning>
  `/api/data/users*` is blocked for all keys. Use `/api/userAuth/*` for user management.
</Warning>

### Required header

`x-api-key`: your `pk_live_…` or `sk_live_…` key.

### Path parameters

<ParamField path="collectionName" type="string" required>
  The name of the collection to query (e.g., `posts`, `comments`, `inventory`).
</ParamField>

### Query parameters

<ParamField query="page" type="number">
  Page number for pagination. Defaults to `1`.
</ParamField>

<ParamField query="limit" type="number">
  Number of documents per page. Defaults to `20`.
</ParamField>

<ParamField query="sort" type="string">
  Field to sort by. Prefix with `-` for descending order (e.g., `sort=-createdAt` for newest
  first, `sort=title` for ascending alphabetical).
</ParamField>

<ParamField query="field_op" type="string">
  Filter documents by field value. Append an operator suffix to the field name for comparisons (e.g., `_gt`, `_lt`, `_ne`, `_in`, `_regex`). For exact matches, use the field name without a suffix. Example: `status=published&views_gt=100`
</ParamField>

<ParamField query="include_deleted" type="boolean">
  Setting `include_deleted` to `true` includes soft-deleted documents; it defaults to `false`
</ParamField>

### RLS behavior

If the collection has **RLS** enabled:

* `public-read` mode: anyone can read all documents with a valid `x-api-key`.
* `private` mode: requires `Authorization: Bearer <accessToken>` — only the owner's documents are returned.

### Response fields

<ResponseField name="success" type="boolean">
  `true` when the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  Object containing the results and pagination metadata.

  <Expandable title="properties">
    <ResponseField name="items" type="array">
      Array of document objects matching the query.
    </ResponseField>

    <ResponseField name="total" type="number">
      Total number of documents matching the query (ignoring pagination).
    </ResponseField>

    <ResponseField name="page" type="number">
      Current page number (present in offset-based pagination).
    </ResponseField>

    <ResponseField name="cursor" type="string">
      Current cursor (present in cursor-based pagination).
    </ResponseField>

    <ResponseField name="nextCursor" type="string">
      Cursor for the next page, or `null`.
    </ResponseField>

    <ResponseField name="limit" type="number">
      Number of results per page.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message.
</ResponseField>

### Code examples

<CodeGroup>
  ```javascript Filtered + paginated theme={null}
  const params = new URLSearchParams({
    page: '1',
    limit: '10',
    sort: '-createdAt',
    status: 'published',
    include_deleted: 'true'
  });

  const res = await fetch(
    `https://api.ub.bitbros.in/api/data/posts?${params}`,
    {
      headers: {
        'x-api-key': 'pk_live_YOUR_KEY'
      }
    }
  );

  const { data } = await res.json();
  // data.items contains the array of matching documents
  // data.total contains the total count
  ```

  ```bash curl theme={null}
  curl "https://api.ub.bitbros.in/api/data/posts?page=1&limit=10&sort=-createdAt&status=published&include_deleted=true" \
    -H "x-api-key: pk_live_YOUR_KEY"
  ```

  ```javascript Private collection (RLS) theme={null}
  const res = await fetch('https://api.ub.bitbros.in/api/data/notes', {
    headers: {
      'x-api-key': 'pk_live_YOUR_KEY',
      'Authorization': `Bearer ${accessToken}` // Required for private-mode collections
    }
  });
  ```
</CodeGroup>

### Success response

```json theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "_id": "64fd1234abcd5678ef901234",
        "title": "Why BaaS is the future",
        "status": "published",
        "isDeleted": false,
        "deletedAt": null,
        "createdAt": "2024-01-15T10:30:00.000Z"
      },
      {
        "_id": "64fd5678abcd1234ef905678",
        "title": "Getting started with urBackend",
        "status": "published",
        "isDeleted": true,
        "deletedAt": "2026-05-20T10:30:00.000Z",
        "createdAt": "2024-01-14T08:00:00.000Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 10
  },
  "message": "Data fetched successfully"
}
```

### Errors

| Status             | Cause                                                                    |
| :----------------- | :----------------------------------------------------------------------- |
| `401 Unauthorized` | Missing/invalid API key, or missing Bearer token on a private collection |
| `403 Forbidden`    | `pk_live` write attempt without RLS, or quota exceeded                   |
| `404 Not Found`    | Collection does not exist                                                |