Admin API

The Circle Admin API is designed for community admins to build automations, migration scripts, and administrative integrations.

Note: the admin API is not meant to be used on the client side, or to re-create your own Circle experience from scratch. If you're looking to build client-side features for your members to interact with your community in your own website or app, please refer to our Headless API.

Fetch your API token

Community admins can obtain an API token by going to the Developers -> Tokens page in their community. Please keep your key private — do not share your key with anyone or make it publicly accessible in any form.

API versions

In September 2024, we'll be introducing the Admin API v2 which addresses several limitations with the v1 API, including:

1. Lack of versioning

2. OpenAPI spec compatibility

3. Performance issues with large datasets

4. Missing endpoints

While v2 API endpoints are still in active development, we expect them to reach parity with our v1 endpoints by December 2024.

See endpoints

• V1

• V2 (default)

Which API version should I use?

After October 2024, we strongly recommend using the admin API v2 whenever possible, and updating your codebase to v2 endpoints if you've built automations with the v1 API.

While we don't plan to deprecate the v1 API any time soon, new endpoints and updates will only be added to our v2 API going forward.

Paginated requests

1. Pagination params:

   • page: This parameter allows you to specify which page of results you want to retrieve. If not provided, it defaults to page 1.

   • per_page: This parameter lets you set how many items you want per page. If not specified, it will default to 10 items per page.

2. Response structure:

   • page: The current page number

   • per_page: The number of items per page

   • has_next_page: A boolean indicating if there are more pages after the current one

   • count: The total number of items across all pages

   • page_count: The total number of pages

   • records: An array containing the data for the current page

3. Example usage: To get the second page with 30 items per page, you would make a request like this:

curl -X GET "https://app.circle.so/api/headless/admin/v1/posts?page=2&per_page=30" \
     -H "Authorization: Bearer <API_Token>" \
     -H "Content-Type: application/json"

Remember, when implementing pagination in your application, it's good practice to respect the has_next_page flag and try not request pages beyond what's available. Also, be aware that the total count might change between requests if new posts are added or removed.

Feedback

• If you have general questions or want to share your creations with the developer community, please check out our Developer community space.

• If you have API feedback for our engineering team, please use this form to reach out to us.