> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-repository-api/core-api-reference/access-control/queries.md).

# Queries

{% hint style="warning" %}
**Navixy Repository API is a work in progress.** This documentation is published for preview purposes only and doesn't reflect a stable release. Structure, field names, and behaviors are subject to change.
{% endhint %}

### roles

Lists roles for an organization.

```graphql
roles(
    organizationId: ID!
    filter: CatalogItemFilter
    first: Int
    after: String
    last: Int
    before: String
    orderBy: CatalogItemOrder = { field: ORDER, direction: ASC }
  ): RoleConnection!
```

**Arguments**

| Name             | Type                | Description                                                                                      |
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| `organizationId` | `ID!`               | The organization to retrieve roles for.                                                          |
| `filter`         | `CatalogItemFilter` | Filtering options for the returned roles.                                                        |
| `first`          | `Int`               | The first `n` elements from the [paginated list](/docs/navixy-repository-api/pagination.md).     |
| `after`          | `String`            | The elements that come after the specified [cursor](/docs/navixy-repository-api/pagination.md).  |
| `last`           | `Int`               | The last `n` elements from the [paginated list](/docs/navixy-repository-api/pagination.md).      |
| `before`         | `String`            | The elements that come before the specified [cursor](/docs/navixy-repository-api/pagination.md). |
| `orderBy`        | `CatalogItemOrder`  | The ordering options for the returned roles.                                                     |

**Input types:**

<details>

<summary>CatalogItemFilter</summary>

Filtering options for catalog items.

| Field           | Type      | Description                                         |
| --------------- | --------- | --------------------------------------------------- |
| `titleContains` | `String`  | Partial match on title (case-insensitive contains). |
| `codes`         | `[Code!]` | Match any of these codes.                           |

</details>

<details>

<summary>CatalogItemOrder</summary>

Ordering options for catalog items.

| Field       | Type                                                                                                                          | Description             |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `field`     | [CatalogItemOrderField](/docs/navixy-repository-api/core-api-reference/catalogs/catalog-items.md#type-catalogitemorderfield)! | The field to order by.  |
| `direction` | [OrderDirection](/docs/navixy-repository-api/core-api-reference/common.md#type-orderdirection)!                               | The direction to order. |

</details>

**Output types:**

<details>

<summary>RoleConnection</summary>

A paginated list of Role items.

**Implements:** [Connection](/docs/navixy-repository-api/core-api-reference/common.md#type-connection)

| Field      | Type                                                                                                  | Description                                                |
| ---------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `edges`    | \[[RoleEdge](/docs/navixy-repository-api/core-api-reference/access-control/types.md#type-roleedge)!]! | A list of edges.                                           |
| `nodes`    | \[[Role](/docs/navixy-repository-api/core-api-reference/access-control/types.md#type-role)!]!         | A list of nodes in the connection (without edge metadata). |
| `pageInfo` | [PageInfo](/docs/navixy-repository-api/core-api-reference/common.md#type-pageinfo)!                   | Information about the current page.                        |
| `total`    | [CountInfo](/docs/navixy-repository-api/core-api-reference/common.md#type-countinfo)                  | The total count of items matching the filter.              |

</details>

<details>

<summary>PageInfo (entity)</summary>

Information about the current page in a paginated connection.

| Field             | Type       | Description                                                |
| ----------------- | ---------- | ---------------------------------------------------------- |
| `hasNextPage`     | `Boolean!` | Whether more items exist after the current page.           |
| `hasPreviousPage` | `Boolean!` | Whether more items exist before the current page.          |
| `startCursor`     | `String`   | The cursor pointing to the first item in the current page. |
| `endCursor`       | `String`   | The cursor pointing to the last item in the current page.  |

</details>

***

### actorRoles

Lists actor role assignments for an organization.

```graphql
actorRoles(
    organizationId: ID!
    filter: ActorRoleFilter
    first: Int
    after: String
    last: Int
    before: String
    orderBy: ActorRoleOrder = { field: ASSIGNED_AT, direction: DESC }
  ): ActorRoleConnection!
```

**Arguments**

| Name             | Type              | Description                                                                                      |
| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------ |
| `organizationId` | `ID!`             | The organization to retrieve actor roles for.                                                    |
| `filter`         | `ActorRoleFilter` | Filtering options for the returned actor roles.                                                  |
| `first`          | `Int`             | The first `n` elements from the [paginated list](/docs/navixy-repository-api/pagination.md).     |
| `after`          | `String`          | The elements that come after the specified [cursor](/docs/navixy-repository-api/pagination.md).  |
| `last`           | `Int`             | The last `n` elements from the [paginated list](/docs/navixy-repository-api/pagination.md).      |
| `before`         | `String`          | The elements that come before the specified [cursor](/docs/navixy-repository-api/pagination.md). |
| `orderBy`        | `ActorRoleOrder`  | The ordering options for the returned actor roles.                                               |

**Input types:**

<details>

<summary>ActorRoleFilter</summary>

Filtering options for actor roles.

| Field            | Type      | Description                         |
| ---------------- | --------- | ----------------------------------- |
| `actorIds`       | `[ID!]`   | Filter by actors (OR within field). |
| `roleIds`        | `[ID!]`   | Filter by roles (OR within field).  |
| `includeExpired` | `Boolean` | Include expired role assignments.   |

</details>

<details>

<summary>ActorRoleOrder</summary>

Ordering options for actor roles.

| Field       | Type                                                                                                                    | Description             |
| ----------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `field`     | [ActorRoleOrderField](/docs/navixy-repository-api/core-api-reference/access-control/types.md#type-actorroleorderfield)! | The field to order by.  |
| `direction` | [OrderDirection](/docs/navixy-repository-api/core-api-reference/common.md#type-orderdirection)!                         | The direction to order. |

</details>

**Output types:**

<details>

<summary>ActorRoleConnection</summary>

A paginated list of ActorRole items.

**Implements:** [Connection](/docs/navixy-repository-api/core-api-reference/common.md#type-connection)

| Field      | Type                                                                                                            | Description                                                |
| ---------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `edges`    | \[[ActorRoleEdge](/docs/navixy-repository-api/core-api-reference/access-control/types.md#type-actorroleedge)!]! | A list of edges.                                           |
| `nodes`    | \[[ActorRole](/docs/navixy-repository-api/core-api-reference/access-control/types.md#type-actorrole)!]!         | A list of nodes in the connection (without edge metadata). |
| `pageInfo` | [PageInfo](/docs/navixy-repository-api/core-api-reference/common.md#type-pageinfo)!                             | Information about the current page.                        |
| `total`    | [CountInfo](/docs/navixy-repository-api/core-api-reference/common.md#type-countinfo)                            | The total count of items matching the filter.              |

</details>

<details>

<summary>PageInfo (entity)</summary>

Information about the current page in a paginated connection.

| Field             | Type       | Description                                                |
| ----------------- | ---------- | ---------------------------------------------------------- |
| `hasNextPage`     | `Boolean!` | Whether more items exist after the current page.           |
| `hasPreviousPage` | `Boolean!` | Whether more items exist before the current page.          |
| `startCursor`     | `String`   | The cursor pointing to the first item in the current page. |
| `endCursor`       | `String`   | The cursor pointing to the last item in the current page.  |

</details>

***

### rolePermissions

Lists role permissions for an organization.

```graphql
rolePermissions(
    organizationId: ID!
    filter: RolePermissionFilter
    first: Int
    after: String
    last: Int
    before: String
    orderBy: RolePermissionOrder = { field: GRANTED_AT, direction: DESC }
  ): RolePermissionConnection!
```

**Arguments**

| Name             | Type                   | Description                                                                                      |
| ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| `organizationId` | `ID!`                  | The organization to retrieve role permissions for.                                               |
| `filter`         | `RolePermissionFilter` | Filtering options for the returned role permissions.                                             |
| `first`          | `Int`                  | The first `n` elements from the [paginated list](/docs/navixy-repository-api/pagination.md).     |
| `after`          | `String`               | The elements that come after the specified [cursor](/docs/navixy-repository-api/pagination.md).  |
| `last`           | `Int`                  | The last `n` elements from the [paginated list](/docs/navixy-repository-api/pagination.md).      |
| `before`         | `String`               | The elements that come before the specified [cursor](/docs/navixy-repository-api/pagination.md). |
| `orderBy`        | `RolePermissionOrder`  | The ordering options for the returned role permissions.                                          |

**Input types:**

<details>

<summary>RolePermissionFilter</summary>

Filtering options for role permissions.

| Field                | Type    | Description                                    |
| -------------------- | ------- | ---------------------------------------------- |
| `roleIds`            | `[ID!]` | Filter by roles (OR within field).             |
| `permissionScopeIds` | `[ID!]` | Filter by permission scopes (OR within field). |
| `targetEntityIds`    | `[ID!]` | Filter by target entities (OR within field).   |

</details>

<details>

<summary>RolePermissionOrder</summary>

Ordering options for role permissions.

| Field       | Type                                                                                                                              | Description             |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `field`     | [RolePermissionOrderField](/docs/navixy-repository-api/core-api-reference/access-control/types.md#type-rolepermissionorderfield)! | The field to order by.  |
| `direction` | [OrderDirection](/docs/navixy-repository-api/core-api-reference/common.md#type-orderdirection)!                                   | The direction to order. |

</details>

**Output types:**

<details>

<summary>RolePermissionConnection</summary>

A paginated list of RolePermission items.

**Implements:** [Connection](/docs/navixy-repository-api/core-api-reference/common.md#type-connection)

| Field      | Type                                                                                                                      | Description                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `edges`    | \[[RolePermissionEdge](/docs/navixy-repository-api/core-api-reference/access-control/types.md#type-rolepermissionedge)!]! | A list of edges.                                           |
| `nodes`    | \[[RolePermission](/docs/navixy-repository-api/core-api-reference/access-control/types.md#type-rolepermission)!]!         | A list of nodes in the connection (without edge metadata). |
| `pageInfo` | [PageInfo](/docs/navixy-repository-api/core-api-reference/common.md#type-pageinfo)!                                       | Information about the current page.                        |
| `total`    | [CountInfo](/docs/navixy-repository-api/core-api-reference/common.md#type-countinfo)                                      | The total count of items matching the filter.              |

</details>

<details>

<summary>PageInfo (entity)</summary>

Information about the current page in a paginated connection.

| Field             | Type       | Description                                                |
| ----------------- | ---------- | ---------------------------------------------------------- |
| `hasNextPage`     | `Boolean!` | Whether more items exist after the current page.           |
| `hasPreviousPage` | `Boolean!` | Whether more items exist before the current page.          |
| `startCursor`     | `String`   | The cursor pointing to the first item in the current page. |
| `endCursor`       | `String`   | The cursor pointing to the last item in the current page.  |

</details>

***

### userScopes

Lists user scope restrictions for an organization.

```graphql
userScopes(
    organizationId: ID!
    filter: UserScopeFilter
    first: Int
    after: String
    last: Int
    before: String
    orderBy: UserScopeOrder = { field: ID, direction: ASC }
  ): UserScopeConnection!
```

**Arguments**

| Name             | Type              | Description                                                                                      |
| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------ |
| `organizationId` | `ID!`             | The organization to retrieve user scopes for.                                                    |
| `filter`         | `UserScopeFilter` | Filtering options for the returned user scopes.                                                  |
| `first`          | `Int`             | The first `n` elements from the [paginated list](/docs/navixy-repository-api/pagination.md).     |
| `after`          | `String`          | The elements that come after the specified [cursor](/docs/navixy-repository-api/pagination.md).  |
| `last`           | `Int`             | The last `n` elements from the [paginated list](/docs/navixy-repository-api/pagination.md).      |
| `before`         | `String`          | The elements that come before the specified [cursor](/docs/navixy-repository-api/pagination.md). |
| `orderBy`        | `UserScopeOrder`  | The ordering options for the returned user scopes.                                               |

**Input types:**

<details>

<summary>UserScopeFilter</summary>

Filtering options for user scopes.

| Field                | Type    | Description                                    |
| -------------------- | ------- | ---------------------------------------------- |
| `actorIds`           | `[ID!]` | Filter by actors (OR within field).            |
| `permissionScopeIds` | `[ID!]` | Filter by permission scopes (OR within field). |
| `targetEntityIds`    | `[ID!]` | Filter by target entities (OR within field).   |

</details>

<details>

<summary>UserScopeOrder</summary>

Ordering options for user scopes.

| Field       | Type                                                                                                                    | Description             |
| ----------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `field`     | [UserScopeOrderField](/docs/navixy-repository-api/core-api-reference/access-control/types.md#type-userscopeorderfield)! | The field to order by.  |
| `direction` | [OrderDirection](/docs/navixy-repository-api/core-api-reference/common.md#type-orderdirection)!                         | The direction to order. |

</details>

**Output types:**

<details>

<summary>UserScopeConnection</summary>

A paginated list of UserScope items.

**Implements:** [Connection](/docs/navixy-repository-api/core-api-reference/common.md#type-connection)

| Field      | Type                                                                                                            | Description                                                |
| ---------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `edges`    | \[[UserScopeEdge](/docs/navixy-repository-api/core-api-reference/access-control/types.md#type-userscopeedge)!]! | A list of edges.                                           |
| `nodes`    | \[[UserScope](/docs/navixy-repository-api/core-api-reference/access-control/types.md#type-userscope)!]!         | A list of nodes in the connection (without edge metadata). |
| `pageInfo` | [PageInfo](/docs/navixy-repository-api/core-api-reference/common.md#type-pageinfo)!                             | Information about the current page.                        |
| `total`    | [CountInfo](/docs/navixy-repository-api/core-api-reference/common.md#type-countinfo)                            | The total count of items matching the filter.              |

</details>

<details>

<summary>PageInfo (entity)</summary>

Information about the current page in a paginated connection.

| Field             | Type       | Description                                                |
| ----------------- | ---------- | ---------------------------------------------------------- |
| `hasNextPage`     | `Boolean!` | Whether more items exist after the current page.           |
| `hasPreviousPage` | `Boolean!` | Whether more items exist before the current page.          |
| `startCursor`     | `String`   | The cursor pointing to the first item in the current page. |
| `endCursor`       | `String`   | The cursor pointing to the last item in the current page.  |

</details>

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://navixy.com/docs/navixy-repository-api/core-api-reference/access-control/queries.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.