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)
archivedAt	Timestamp	When the circle was archived; null if active
createdAt	Timestamp	When the circle was created

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
    }
  }
}

Move a Circle

A circle’s only directly updatable field is its parentId (moving it under another circle).

mutation MoveCircle {
  update_circle_by_pk(
    pk_columns: { id: "circle-id" }
    _set: { parentId: "new-parent-circle-id" }
  ) {
    id
    parentId
  }
}

Permissions

Circle access follows the organization’s governanceMode. In Free mode any member can modify the org chart. In Agile mode a circle’s leaders modify it directly. In Strict mode structural changes go through proposals, while organization owners can always edit.