List circles
GET/circles●Query circles with filtering, sorting, and pagination.
Use this endpoint to review security groups in the system, audit group configurations, or find circles referenced in access policies.
Supported filters:
data.schema— circle schemameta.status— record statusmeta.labels— record labelsmeta.domain— domain scopedata.custom.<field>— any custom field (may be slower on large datasets)
Usage Examples
curl -X GET "http://localhost:3000/v2/circles" \ -H "x-ledger: <YOUR LEDGER HANDLE>"{
"hash": "80deca2bc1f44536f688817591d2d57a9a23ad69d27ed24d65308c6083428618",
"data": [
{
"luid": "$crc.-01xK3tUvW4fU6yZ5",
"hash": "855bc7d94e12eb5ed2f58af16dd6dbcedeeb2d3f80340d9fbc8976fd1c31dc7c",
"data": {
"handle": "admin"
},
"meta": {
"status": "created",
"moment": "2025-04-05T14:30:00.050Z",
"owners": [
"AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8="
],
"proofs": [
{
"signer": "ach-admin",
"method": "ed25519-v2",
"digest": "4ad98da772474baaba41b5425773586cd23f1e8d7514b7b7776012842c446953",
"public": "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8=",
"result": "YZyvyq8MGm3X35i7J31JlPVbGwekquXAw+nL6M0JiU3H7Dxcg/de2rd3cCSwYywxq5+5rBvCl38g+gdrJs9nAA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z",
"status": "created"
}
},
{
"signer": "system",
"method": "ed25519-v2",
"digest": "2bee4f906deb32ffd75b7e1d88f0d45fafdf6d658cfd1d68bcb890e020b3915c",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "28PT93eVJSWAlNPZtX7yMz/ykDCxQ0YDtgVwV6WfsIBk0nQvRFqsqXurxbLCJfTj2IcbE0b5MdAcfS8stOZ+Ag==",
"custom": {
"luid": "$crc.-01xK3tUvW4fU6yZ5",
"moment": "2025-04-05T14:30:00.050Z",
"status": "created"
}
}
]
}
},
{
"luid": "$crc.-01xG51Y5tfEE7zA5",
"hash": "c294641489a98dc07edff0d3492098392cf368ec64340eb430b6bbc05385f9c9",
"data": {
"handle": "support",
"parent": "855bc7d94e12eb5ed2f58af16dd6dbcedeeb2d3f80340d9fbc8976fd1c31dc7c",
"custom": {
"description": "Support team access circle"
}
},
"meta": {
"status": "created",
"moment": "2025-04-05T14:21:40.025Z",
"owners": [
"AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8="
],
"proofs": [
{
"signer": "ach-admin",
"method": "ed25519-v2",
"digest": "4ca7eafe2800aff93e445ebc3ddde97704ea034e6cda7a408d5597d0487a45f9",
"public": "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8=",
"result": "ZF5BWY4Bqt5yPjEQFeOsjN7g72L9k2ZOMWlYXKjktyjf1N99ThTMVA06n81R47VjBz5xrXZP2OW9kihsmfjNAw==",
"custom": {
"moment": "2025-04-05T14:21:40.000Z",
"status": "created"
}
},
{
"signer": "system",
"method": "ed25519-v2",
"digest": "a7b9467a3acf2f9b302f9fe341382883861049e74872353aa3c7419fe1ce3034",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "/n4fj5MOrbOwzzDNbXVv7xkdlLBboW7+ewjIUB0Z8u5AWw52WMwtH6oSargmIOoOOH3DPd2uVeKsVY3EJ1ixCw==",
"custom": {
"luid": "$crc.-01xG51Y5tfEE7zA5",
"moment": "2025-04-05T14:21:40.025Z",
"status": "created"
}
}
]
}
}
],
"page": {
"index": 0,
"limit": 20
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "25a597505241e058ed2503fcada7a157f4d22a5d7f556a6daa0ceab58a682a32",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "qsY5HJu3s0V/5fp0GDmH5Hm6yUqLgGvsgUv6ESKLn2e09EO9JeDQCwp9KpRzSD3Z2EXYcUqnohY7iFhq89JjCQ==",
"custom": {
"moment": "2025-04-05T14:30:00.100Z"
}
}
]
}
}{
"hash": "b7eb7ccf5ffc126951e13e29a8dcfdaf95db859715d4edfc2d16f59a79d4cd58",
"data": {
"reason": "auth.unauthorized",
"detail": "Invalid token."
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "3acece870c4118bfe4223118e4d2f3cfd5b8947a7093785b66d49aa57fa2890a",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "gnK63DqqWDY/UXvnZHixDKPKS6tfeGHgdARylnPiJLwQGyYxuD97TYbSg2wrzsf/bDrHwQYZaf8Gu5ryYP0UAA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "9ec02726b50650add8acfd124c6defeb978a9ac252a5de888f9493ddc701e927",
"data": {
"reason": "auth.forbidden",
"detail": "Request is not authorized"
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "4f8cbdc38d73348de0c31805c783c84a0fecc6be736d7e187004ba68cd00e675",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "P3hRnveehtuobb4AIO56XBmiduvmYJbpdmOHltG/IifBEH7QSWdv/0pqled4SO9x1Ne3oXuWxJy40DzMvx1MBA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "bd1e78b47e837376b7994e3e481aa547c110c4d6a1c1d8ecd047cc465edd33bd",
"data": {
"reason": "api.request-timeout",
"detail": "Processing of request on server timed out. Your request may or may not have been processed."
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "cdf5b09c809ec52934cd76ca3b0aa59310049e3cae8b171aee3cf9e0f98bddb2",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "6h1lhq3TOccWrfIdtOa9pkz9pIHVAN9tyXuNaucvLpbspWACog6HpSAdr0FSwGzn0zAKwx8YppGOVjFhfeBLBw==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "1c084e8dcfb9bb84bc8ea96e9e137b149a34b2bbd85f8e60b4263f5aba980476",
"data": {
"custom": {
"errors": [
{
"instancePath": "/handle",
"schemaPath": "#/properties/handle/pattern",
"keyword": "pattern",
"params": {
"pattern": "^[a-zA-Z0-9_\\-+.]+$"
},
"message": "must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
}
]
},
"reason": "record.schema-invalid",
"detail": "Schema validator error: data.handle must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "7a5febb431719b6f43d7e88e79211308e16ac651b71b339276373fdb4e7c3760",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "2/1zYw4AaIzsIHfOIC6V/CHw6owbjYHt48cwmFOig0ibeT0IbojLmj1RCRi8W00ka0udPa9WsacWDd7ObMY8CA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "93a5f4d97a42c2df97f827c58ff7768d02568c15aca931e22b81fa3160ba0df3",
"data": {
"reason": "api.unexpected-error",
"detail": "An unexpected error occurred"
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "efaf5360143b586917d9636779ad6e08571c5b06909a20dd0f5eba4bf3be7eae",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "hERh6Aecj59iR+Fb25OQsHJScOi4t8EiffKSfjlMQdjHMccTnfDlgZFdaJzXzUtpSwy/NHq0l+7ydh3HSWCoAg==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}Query Parameters
page?
Pagination options. Set limit and index to page through results.
filter?
Filter by field values using dot notation (e.g. data.handle=value). Operators like $in and $regex are optional — equality is the default.
Header Parameters
x-ledger?|
The unique identifier of ledger in context for multi tenant requests.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
Create circle POST
After creation, add signers to the circle using the circle signer endpoints. Policies can then reference the circle to grant permissions to all its members at once. Broadcasts the `circle-created` signal. Use [effects](/ledger/reference/api/effect) to subscribe.
Get circle GET
Next Page