openapi: 3.0.3
info:
title: Circle Developer Platform API
description: >-
Circle (circle.so) is an all-in-one community platform for creators, coaches,
and brands. This description grounds Circle's documented public developer
platform into a single OpenAPI file for discovery. It covers two admin- or
member-authenticated REST surfaces: the Admin API V2 (base
https://app.circle.so/api/admin/v2) for community administration and
automation, and the Headless Member API (base
https://app.circle.so/api/headless/v1) for building your own member-facing
experience, plus the Headless Auth API token exchange. Admin API requests use
an "Authorization: Token AUTH_TOKEN" header; Headless Member API requests use
a member-scoped JWT in an "Authorization: Bearer ACCESS_TOKEN" header issued
by the Auth API. API access is gated to the Business plan and above. This is
the community-software company at circle.so, NOT the USDC / stablecoin
financial-services company. Paths shown are a representative, grounded subset
of the full reference published at api-headless.circle.so.
version: '2.0'
contact:
name: Circle
url: https://circle.so
license:
name: Proprietary
url: https://circle.so/terms
servers:
- url: https://app.circle.so
description: Circle production
security:
- tokenAuth: []
tags:
- name: Admin - Members
description: Admin-authenticated community member management.
- name: Admin - Spaces
description: Spaces, space groups, and their memberships.
- name: Admin - Posts
description: Posts, comments, and topics.
- name: Admin - Events
description: Events and event attendees.
- name: Admin - Courses
description: Course sections, lessons, and progress.
- name: Headless - Auth
description: Member JWT token exchange for the Headless Member API.
- name: Headless - Member
description: Member-authenticated experience endpoints.
paths:
/api/admin/v2/community_members:
get:
tags: [Admin - Members]
summary: List community members
security:
- tokenAuth: []
parameters:
- { name: page, in: query, schema: { type: integer, default: 1 } }
- { name: per_page, in: query, schema: { type: integer, default: 10 } }
responses:
'200': { description: A page of community members. }
post:
tags: [Admin - Members]
summary: Invite or create a community member
security:
- tokenAuth: []
responses:
'200': { description: The created or invited member. }
/api/admin/v2/community_members/search:
get:
tags: [Admin - Members]
summary: Search community members
security:
- tokenAuth: []
responses:
'200': { description: Matching community members. }
/api/admin/v2/community_members/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: integer } }
get:
tags: [Admin - Members]
summary: Retrieve a community member
security:
- tokenAuth: []
responses:
'200': { description: The community member. }
put:
tags: [Admin - Members]
summary: Update a community member
security:
- tokenAuth: []
responses:
'200': { description: The updated member. }
delete:
tags: [Admin - Members]
summary: Delete a community member
security:
- tokenAuth: []
responses:
'200': { description: Deletion result. }
/api/admin/v2/community_members/{id}/ban_member:
put:
tags: [Admin - Members]
summary: Ban a community member
security:
- tokenAuth: []
parameters:
- { name: id, in: path, required: true, schema: { type: integer } }
responses:
'200': { description: Ban result. }
/api/admin/v2/member_tags:
get:
tags: [Admin - Members]
summary: List member tags
security:
- tokenAuth: []
responses:
'200': { description: A page of member tags. }
post:
tags: [Admin - Members]
summary: Create a member tag
security:
- tokenAuth: []
responses:
'200': { description: The created member tag. }
/api/admin/v2/tagged_members:
get:
tags: [Admin - Members]
summary: List tagged members
security:
- tokenAuth: []
responses:
'200': { description: Members carrying a given tag. }
post:
tags: [Admin - Members]
summary: Apply a tag to a member
security:
- tokenAuth: []
responses:
'200': { description: The tag assignment. }
delete:
tags: [Admin - Members]
summary: Remove a tag from a member
security:
- tokenAuth: []
responses:
'200': { description: Removal result. }
/api/admin/v2/spaces:
get:
tags: [Admin - Spaces]
summary: List spaces
security:
- tokenAuth: []
responses:
'200': { description: A page of spaces. }
post:
tags: [Admin - Spaces]
summary: Create a space
security:
- tokenAuth: []
responses:
'200': { description: The created space. }
/api/admin/v2/spaces/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: integer } }
get:
tags: [Admin - Spaces]
summary: Retrieve a space
security:
- tokenAuth: []
responses:
'200': { description: The space. }
put:
tags: [Admin - Spaces]
summary: Update a space
security:
- tokenAuth: []
responses:
'200': { description: The updated space. }
delete:
tags: [Admin - Spaces]
summary: Delete a space
security:
- tokenAuth: []
responses:
'200': { description: Deletion result. }
/api/admin/v2/space_groups:
get:
tags: [Admin - Spaces]
summary: List space groups
security:
- tokenAuth: []
responses:
'200': { description: A page of space groups. }
post:
tags: [Admin - Spaces]
summary: Create a space group
security:
- tokenAuth: []
responses:
'200': { description: The created space group. }
/api/admin/v2/space_members:
get:
tags: [Admin - Spaces]
summary: List space members
security:
- tokenAuth: []
responses:
'200': { description: A page of space members. }
post:
tags: [Admin - Spaces]
summary: Add a member to a space
security:
- tokenAuth: []
responses:
'200': { description: The added space member. }
delete:
tags: [Admin - Spaces]
summary: Remove a member from a space
security:
- tokenAuth: []
responses:
'200': { description: Removal result. }
/api/admin/v2/posts:
get:
tags: [Admin - Posts]
summary: List posts
security:
- tokenAuth: []
parameters:
- { name: page, in: query, schema: { type: integer, default: 1 } }
- { name: per_page, in: query, schema: { type: integer, default: 10 } }
responses:
'200': { description: A page of posts. }
post:
tags: [Admin - Posts]
summary: Create a post
security:
- tokenAuth: []
responses:
'200': { description: The created post. }
/api/admin/v2/posts/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: integer } }
get:
tags: [Admin - Posts]
summary: Retrieve a post
security:
- tokenAuth: []
responses:
'200': { description: The post. }
put:
tags: [Admin - Posts]
summary: Update or move a post
security:
- tokenAuth: []
responses:
'200': { description: The updated post. }
delete:
tags: [Admin - Posts]
summary: Delete a post
security:
- tokenAuth: []
responses:
'200': { description: Deletion result. }
/api/admin/v2/posts/{post_id}/summary:
get:
tags: [Admin - Posts]
summary: Get an AI summary of a post
security:
- tokenAuth: []
parameters:
- { name: post_id, in: path, required: true, schema: { type: integer } }
responses:
'200': { description: The post summary. }
/api/admin/v2/comments:
get:
tags: [Admin - Posts]
summary: List comments
security:
- tokenAuth: []
responses:
'200': { description: A page of comments. }
post:
tags: [Admin - Posts]
summary: Create a comment
security:
- tokenAuth: []
responses:
'200': { description: The created comment. }
/api/admin/v2/comments/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: integer } }
get:
tags: [Admin - Posts]
summary: Retrieve a comment
security:
- tokenAuth: []
responses:
'200': { description: The comment. }
delete:
tags: [Admin - Posts]
summary: Delete a comment
security:
- tokenAuth: []
responses:
'200': { description: Deletion result. }
/api/admin/v2/topics:
get:
tags: [Admin - Posts]
summary: List topics
security:
- tokenAuth: []
responses:
'200': { description: A page of topics. }
post:
tags: [Admin - Posts]
summary: Create a topic
security:
- tokenAuth: []
responses:
'200': { description: The created topic. }
/api/admin/v2/events:
get:
tags: [Admin - Events]
summary: List events
security:
- tokenAuth: []
responses:
'200': { description: A page of events. }
post:
tags: [Admin - Events]
summary: Create an event
security:
- tokenAuth: []
responses:
'200': { description: The created event. }
/api/admin/v2/events/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: integer } }
get:
tags: [Admin - Events]
summary: Retrieve an event
security:
- tokenAuth: []
responses:
'200': { description: The event. }
put:
tags: [Admin - Events]
summary: Update an event
security:
- tokenAuth: []
responses:
'200': { description: The updated event. }
delete:
tags: [Admin - Events]
summary: Delete an event
security:
- tokenAuth: []
responses:
'200': { description: Deletion result. }
/api/admin/v2/event_attendees:
get:
tags: [Admin - Events]
summary: List event attendees
security:
- tokenAuth: []
responses:
'200': { description: A page of attendees. }
post:
tags: [Admin - Events]
summary: Add an event attendee
security:
- tokenAuth: []
responses:
'200': { description: The added attendee. }
delete:
tags: [Admin - Events]
summary: Remove an event attendee
security:
- tokenAuth: []
responses:
'200': { description: Removal result. }
/api/admin/v2/course_sections:
get:
tags: [Admin - Courses]
summary: List course sections
security:
- tokenAuth: []
responses:
'200': { description: A page of course sections. }
post:
tags: [Admin - Courses]
summary: Create a course section
security:
- tokenAuth: []
responses:
'200': { description: The created section. }
/api/admin/v2/course_lessons:
get:
tags: [Admin - Courses]
summary: List course lessons
security:
- tokenAuth: []
responses:
'200': { description: A page of course lessons. }
post:
tags: [Admin - Courses]
summary: Create a course lesson
security:
- tokenAuth: []
responses:
'200': { description: The created lesson. }
/api/admin/v2/course_lessons/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: integer } }
get:
tags: [Admin - Courses]
summary: Retrieve a course lesson
security:
- tokenAuth: []
responses:
'200': { description: The course lesson. }
patch:
tags: [Admin - Courses]
summary: Update a course lesson
security:
- tokenAuth: []
responses:
'200': { description: The updated lesson. }
delete:
tags: [Admin - Courses]
summary: Delete a course lesson
security:
- tokenAuth: []
responses:
'200': { description: Deletion result. }
/api/admin/v2/course_lesson_progress:
put:
tags: [Admin - Courses]
summary: Set a member's course lesson progress
security:
- tokenAuth: []
responses:
'200': { description: Updated progress. }
/api/v1/headless/auth_token:
post:
tags: [Headless - Auth]
summary: Exchange a headless auth token for a member JWT
description: >-
Server-to-server exchange of a community-level headless auth token for a
member-scoped JWT access token plus refresh token. Access tokens expire
after one hour.
security:
- bearerAuth: []
responses:
'200':
description: The issued access and refresh tokens.
content:
application/json:
schema:
$ref: '#/components/schemas/HeadlessAuthToken'
/api/headless/v1/home:
get:
tags: [Headless - Member]
summary: Get the member home feed
security:
- bearerAuth: []
responses:
'200': { description: The member's home feed. }
/api/headless/v1/spaces:
get:
tags: [Headless - Member]
summary: List spaces visible to the member
security:
- bearerAuth: []
responses:
'200': { description: The member's spaces. }
/api/headless/v1/spaces/{id}/join:
post:
tags: [Headless - Member]
summary: Join a space
security:
- bearerAuth: []
parameters:
- { name: id, in: path, required: true, schema: { type: integer } }
responses:
'200': { description: Join result. }
/api/headless/v1/spaces/{space_id}/posts:
get:
tags: [Headless - Member]
summary: List posts in a space
security:
- bearerAuth: []
parameters:
- { name: space_id, in: path, required: true, schema: { type: integer } }
responses:
'200': { description: A page of posts. }
post:
tags: [Headless - Member]
summary: Create a post in a space
security:
- bearerAuth: []
parameters:
- { name: space_id, in: path, required: true, schema: { type: integer } }
responses:
'200': { description: The created post. }
/api/headless/v1/posts/{post_id}/comments:
get:
tags: [Headless - Member]
summary: List comments on a post
security:
- bearerAuth: []
parameters:
- { name: post_id, in: path, required: true, schema: { type: integer } }
responses:
'200': { description: A page of comments. }
post:
tags: [Headless - Member]
summary: Comment on a post
security:
- bearerAuth: []
parameters:
- { name: post_id, in: path, required: true, schema: { type: integer } }
responses:
'200': { description: The created comment. }
/api/headless/v1/posts/{post_id}/user_likes:
post:
tags: [Headless - Member]
summary: Like a post
security:
- bearerAuth: []
parameters:
- { name: post_id, in: path, required: true, schema: { type: integer } }
responses:
'200': { description: Like result. }
/api/headless/v1/community_events:
get:
tags: [Headless - Member]
summary: List community events
security:
- bearerAuth: []
responses:
'200': { description: A page of community events. }
/api/headless/v1/events/{event_id}/event_attendees:
post:
tags: [Headless - Member]
summary: RSVP to an event
security:
- bearerAuth: []
parameters:
- { name: event_id, in: path, required: true, schema: { type: integer } }
responses:
'200': { description: The RSVP. }
/api/headless/v1/courses/{course_id}/sections:
get:
tags: [Headless - Member]
summary: List course sections
security:
- bearerAuth: []
parameters:
- { name: course_id, in: path, required: true, schema: { type: integer } }
responses:
'200': { description: The course sections. }
/api/headless/v1/courses/{course_id}/lessons/{id}:
get:
tags: [Headless - Member]
summary: Get a course lesson
security:
- bearerAuth: []
parameters:
- { name: course_id, in: path, required: true, schema: { type: integer } }
- { name: id, in: path, required: true, schema: { type: integer } }
responses:
'200': { description: The course lesson. }
/api/headless/v1/messages:
get:
tags: [Headless - Member]
summary: List chat rooms / direct messages
security:
- bearerAuth: []
responses:
'200': { description: The member's chat rooms. }
post:
tags: [Headless - Member]
summary: Start a chat room / direct message
security:
- bearerAuth: []
responses:
'200': { description: The created chat room. }
/api/headless/v1/messages/{chat_room_uuid}/chat_room_messages:
get:
tags: [Headless - Member]
summary: List messages in a chat room
security:
- bearerAuth: []
parameters:
- { name: chat_room_uuid, in: path, required: true, schema: { type: string } }
responses:
'200': { description: A page of chat messages. }
post:
tags: [Headless - Member]
summary: Send a message to a chat room
security:
- bearerAuth: []
parameters:
- { name: chat_room_uuid, in: path, required: true, schema: { type: string } }
responses:
'200': { description: The sent message. }
/api/headless/v1/notifications:
get:
tags: [Headless - Member]
summary: List notifications
security:
- bearerAuth: []
responses:
'200': { description: A page of notifications. }
/api/headless/v1/profile:
put:
tags: [Headless - Member]
summary: Update the member profile
security:
- bearerAuth: []
responses:
'200': { description: The updated profile. }
components:
securitySchemes:
tokenAuth:
type: apiKey
in: header
name: Authorization
description: >-
Admin API token in the format "Token AUTH_TOKEN". Community admins
generate the token on the Developers -> Tokens page.
bearerAuth:
type: http
scheme: bearer
description: >-
Member-scoped JWT access token from /api/v1/headless/auth_token in the
format "Bearer ACCESS_TOKEN". Expires after one hour.
schemas:
HeadlessAuthToken:
type: object
properties:
access_token: { type: string }
refresh_token: { type: string }
access_token_expires_at: { type: string }
refresh_token_expires_at: { type: string }
community_member_id: { type: integer }
community_id: { type: integer }