---
title: "Circle"
url: "https://rolebase.io/en/api/circle"
---

[Rolebase](/) ⟩ [API Reference](/en/api)

 API Reference

# `circle`

Represents a hierarchical organizational circle that can contain members, roles, and child circles. Circles organize teams and responsibilities within an organization.

## Fields

Field

Type

Description

`id`

`uuid`

Unique identifier for the circle

`orgId`

`uuid`

Reference to the organization

`roleId`

`uuid`

Reference to the role associated with this circle

`parentId`

`uuid`

Reference to the parent circle (optional, null for top-level circles)

`archived`

`Boolean`

Whether the circle is archived (default: false)

## Relationships

**Object Relationships:**

*   `org` — The organization this circle belongs to
*   `parent` — The parent circle (if any)
*   `role` — The role that defines this circle’s purpose and accountabilities

**Array Relationships:**

*   `children` — Child circles within this circle
*   `members` — Circle memberships
*   `leaders` — Circle leadership assignments
*   `participants` — All participants (including inherited from child circles)
*   `meetings` — Meetings associated with this circle
*   `meetings_recurring` — Recurring meetings for this circle
*   `tasks` — Tasks assigned to this circle
*   `decisions` — Decisions made within this circle
*   `threads` — Discussion threads in this circle
*   `hostCircleLinks` — Links where this circle hosts other circles
*   `invitedCircleLinks` — Links where this circle is invited to other circles

## Query Examples

### List Circles in an Organization

```
query GetCircles($orgId: uuid!) {
  circle(where: { orgId: { _eq: $orgId } }) {
    id
    role {
      name
      purpose
    }
    members {
      member {
        name
      }
    }
    children {
      id
      role {
        name
      }
    }
    parent {
      id
      role {
        name
      }
    }
  }
}
```

### Get a Specific Circle

```
query GetCircle($id: uuid!) {
  circle_by_pk(id: $id) {
    id
    role {
      name
    }
  }
}
```

## Mutation Examples

### Create a Circle

```
mutation CreateCircle {
  insert_circle_one(
    object: {
      orgId: "your-org-id"
      roleId: "role-id"
      parentId: "parent-circle-id"
    }
  ) {
    id
    role {
      name
    }
  }
}
```

### Update a Circle

```
mutation UpdateCircle {
  update_circle_by_pk(
    pk_columns: { id: "circle-id" }
    _set: { archived: true }
  ) {
    id
    archived
  }
}
```

## Permissions

Circle access follows organization and governance rules. When `protectGovernance` is enabled on the organization, only circle leaders can modify circle structure.

** Notes**

Circles form a hierarchical tree through the `parentId` relationship. Each circle must have an associated role that defines its purpose and accountabilities. Circle participants include direct members plus leaders of child and linked circles. Meetings, tasks, and decisions are organized within circles.