# Search Permission Items

Operation ID: `searchPermissionItems`

Group: Base › Permissions

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/searchPermissionItems)

`POST /base/permissions/search`

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches the permission roles or tasks that are available to default users. The results are ordered by how well they match the query.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · v1 | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |

## Request body

Required, `application/json`: searchPermissionItemsInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `queryString` | string | yes | The text to match against the name and description of each permission. Must have 3 or more characters. |
| `permissionType` | any | yes | The kind of permission to search: 'roles' or 'tasks'. One of: `"tasks"`, `"roles"`. |
| `limit` | number | no | The maximum number of results. Must be greater than 0. Defaults to 5. |

```json
{
  "queryString": "<queryString>",
  "permissionType": "tasks",
  "limit": 0
}
```

## Response

`200` Success

Under `data` (searchPermissionItemsOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `permissions` | array<object> | yes | The matching permissions, best match first. |
| `permissions[].name` | string | yes | The name of the permission. |
| `permissions[].description` | string | no | The description of the permission. |
| `permissions[].uuid` | string | yes | The unique identifier for the permission. |
| `permissions[].package` | string | yes | The package that owns the permission. |
| `permissionType` | any | yes | The kind of permission that was searched. One of: `"tasks"`, `"roles"`. |

```json
{
  "data": {
    "permissions": [
      {
        "name": "<name>",
        "description": "<description>",
        "uuid": "<uuid>",
        "package": "<package>"
      }
    ],
    "permissionType": "tasks"
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Errors

| Code | Status |
| --- | --- |
| `INVALID_LIMIT` | 400 |
| `QUERY_STRING_TOO_SHORT` | 400 |

## Statuses

- `400` — Invalid request or business failure. Codes: INVALID_LIMIT, QUERY_STRING_TOO_SHORT
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error