circle

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.