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 }