Common Room

Common Room Segments API

The Segments API from Common Room — 3 operation(s) for segments.

GitHub OpenAPI
Business capability
Customer Segmentation Management BC-420.20

Operations 5

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /segments List all segments in a room · Get segments in a room #
Ask an LLM
“What segments exist in our Common Room room?”
“Can I get a list of every segment we've built?”
Tell an agent
List all segments in our room.
Show me every segment we have.
POST /segments Create a new segment · Create a segment #
Ask an LLM
“How do I create a new segment in our community?”
“Can a new segment hold organizations or custom objects instead of contacts?”
Tell an agent
Create a segment named {name}.
Create segment {name} described as {description} for {entityType} records.
GET /segments/{id}/status List the statuses available in a segment · Gets all status for a segment #
Ask an LLM
“Which statuses can contacts have inside a particular segment?”
“How do I find the status IDs defined for a segment?”
Tell an agent
List all statuses for segment {id}.
Get the status options configured on segment {id}.
POST /segments/{id} Add existing contacts to a segment · Add Contact(s) to Segment #
Ask an LLM
“How do I add contacts to a segment using their email addresses?”
“Can I add people to a segment by GitHub, Twitter or LinkedIn handle?”
Tell an agent
Add the contacts with {socialType} values {value} to segment {id}.
Add {socialType} contacts {value} to segment {id} with status {statusId}.
GET /segments/{id} Get one segment by its ID · Get a segment by ID #
Ask an LLM
“Can I look up a single segment's details from its s_ ID?”
“How many records are in a specific segment, and what's its URL?”
Tell an agent
Get segment {id}.
Fetch segment {id} with its {cols}.

Documentation

📖
Documentation
https://api.commonroom.io/docs/community.html

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/common-room/refs/heads/main/openapi/common-room-segments-api-openapi.yml

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/common-room/refs/heads/main/overlays/common-room-segments-api-overlay.yaml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/common-room:common-room-segments-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

common-room-segments-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Common Room Segments API
  x-logo:
    url: /common-room-api-logo.svg
  version: '1.0'
  description: 'Operations tagged Segments across 2 of this provider''s published API definitions: common-room-core-openapi.yml, common-room-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.commonroom.io/community/v1
  description: Common Room Core API v1
- url: https://api.commonroom.io/community/v2
  description: Common Room API v2
tags:
- name: Segments
paths:
  /segments:
    get:
      description: Gets all segments in a room
      summary: Get segments in a room
      tags:
      - Segments
      operationId: getSegments
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: number
                      description: Segment id
                    name:
                      type: string
                      description: Display name of segment
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      summary: Create a segment
      description: Create a new segment in the community.
      tags:
      - Segments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSegmentRequest'
      responses:
        '201':
          description: Created
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSegmentResponse'
        '400':
          description: Bad Request (e.g. invalid parameters or missing required fields)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '409':
          description: Conflict (a segment with this name already exists)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postSegments
      x-operation-id-source: derived
    servers:
    - url: https://api.commonroom.io/community/v1
      description: Common Room Core API v1
  /segments/{id}/status:
    get:
      summary: Gets all status for a segment
      tags:
      - Segments
      operationId: getSegmentStatuses
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: number
                      description: Status id
                    name:
                      type: string
                      description: Display text of status
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://api.commonroom.io/community/v1
      description: Common Room Core API v1
  /segments/{id}:
    post:
      description: Add existing contacts to an existing segment
      summary: Add Contact(s) to Segment
      deprecated: true
      tags:
      - Segments
      operationId: addContactsToSegment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                socialType:
                  type: string
                  example: email
                  description: Must be email, twitter, github, or linkedin
                value:
                  type: string
                  example: email@domail.com, email2@domain.org
                  description: Comma separated list of values corresponding to socialType
                statusId:
                  type: number
                  example: 1234
              required:
              - socialType
              - value
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '404':
          description: Not Found
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
        '429':
          $ref: '#/components/responses/RateLimited'
    get:
      summary: Get a segment by ID
      description: Retrieve a specific segment by its unique identifier.
      tags:
      - Segments
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The prefixed segment ID (format `s_<number>`)
      - name: cols
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated list of additional columns to include in the response.

          Valid values: `entityCount`, `url`.

          '
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentResponse'
        '400':
          description: Bad Request (e.g. invalid segment ID or invalid parameters)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '404':
          description: Segment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getSegmentsById
      x-operation-id-source: derived
    servers:
    - url: https://api.commonroom.io/community/v1
      description: Common Room Core API v1
components:
  headers:
    X-RateLimit-Remaining:
      description: The total amount of requests remaining within the interval
      schema:
        type: integer
    X-RateLimit-Limit:
      description: The total amount of requests permitted within the interval
      schema:
        type: integer
  responses:
    InvalidRequest:
      description: Invalid Request
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
      content:
        application/json:
          schema:
            type: object
            properties:
              reason:
                type: string
                description: A reason of `invalid-request-body` indicates that the request body did not match the schema required by our API docs. Please double-check that your request body matches the schema above, and contact us for help if you continue to experience issues.
              docs:
                type: string
                description: A link to this API documentation
    RateLimited:
      description: Rate Limited
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          description: The datetime in epoch seconds when the interval resets
          schema:
            type: integer
        Retry-After:
          description: The UTC datetime when the interval resets
          schema:
            type: string
            format: date-time
      content:
        application/json:
          schema:
            type: object
            properties:
              reason:
                type: string
              rateLimit:
                type: object
                description: A summary of the rate limit encountered, additional information is available in the headers.
                properties:
                  intervalLimit:
                    type: number
                    description: The total amount of requests permitted within the interval
                  intervalRemaining:
                    type: number
                    description: The amount of requests remaining within the interval
                  intervalResetSeconds:
                    type: number
                    description: The amount of time in seconds representing a single interval
                  waitMs:
                    type: number
                    description: The amount of time to wait until the next interval
  schemas:
    SegmentList:
      type: object
      required:
      - success
      - data
      - meta
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          type: array
          items:
            $ref: '#/components/schemas/ApiSegment'
        meta:
          type: object
          properties:
            nextCursor:
              type:
              - string
              - 'null'
              description: Cursor for pagination; pass as the `cursor` query parameter to fetch the next page.
            recordCount:
              type: integer
              description: Total number of records matching the query. Only returned when `cols=recordCount` is requested.
    ApiV2ErrorResponse:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          $ref: '#/components/schemas/ApiV2Error'
    Status:
      type: object
      properties:
        status:
          type: string
          enum:
          - ok
          - failure
          - not-found
          example: success
        reason:
          type: string
        errors:
          type: array
          items:
            type: string
          required:
          - status
      example:
        status: not created
        errors:
        - name is missing
    CreateSegmentResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          type: object
          required:
          - id
          - name
          properties:
            id:
              type: string
              description: Prefixed segment ID (format `s_<number>`)
            name:
              type: string
    ApiSegment:
      type: object
      required:
      - id
      - name
      - entityType
      properties:
        id:
          type: string
          description: Prefixed segment ID (format `s_<number>`)
        name:
          type: string
          description: The segment's display name
        entityType:
          type: string
          enum:
          - contact
          - object
          - organization
          description: The type of entity this segment contains
        entityCount:
          type: integer
          description: Number of entities in this segment
        url:
          type: string
          format: uri
          description: Common Room URL for this segment
    CreateSegmentRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The name for the new segment (max 500 characters)
        description:
          type: string
          description: Optional description for the segment (markdown supported)
        entityType:
          type: string
          enum:
          - contact
          - object
          - organization
          default: contact
          description: The type of entity this segment will contain
        objectTypeId:
          type: string
          description: Required when entityType is `object`. Prefixed object type ID (format `cot_<number>`)
    ApiV2Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: A machine-readable error code identifying the failure.
          enum:
          - invalid_parameters
          - invalid_organization_id
          - org_not_found
          - invalid_contact_id
          - contact_not_found
          - invalid_object_id
          - object_not_found
          - invalid_object_type_id
          - object_type_not_found
          - invalid_segment_id
          - segment_not_found
          - invalid_activity_id
          - activity_not_found
          - conflict
          - internal_server_error
          - invalid_custom_field_id
          - custom_field_not_found
          - invalid_prospector_contact_id
          - prospector_contact_not_found
          - invalid_prospector_company_id
          - prospector_company_not_found
        message:
          type: string
          description: A human-readable description of the error.
    SegmentResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          $ref: '#/components/schemas/ApiSegment'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Use a Core API JWT as a Bearer token in the Authentication header.\n\nTokens can be created by room Admins through https://app.commonroom.io/\n\nExample:\n\n```\ncurl -H \"Authorization: Bearer abcd123.xzy\" \\\n  https://api.commonroom.io/community/v1/api-token-status\n````\n"
x-refined-from:
- common-room-core-openapi.yml
- common-room-v2-openapi.yml