OpenAPI Specification
openapi: 3.0.0
info:
title: Common Room Core Activities Topics API
version: 1.0.0
description: "Common Room Core REST APIs for getting data in to Common Room.\n<br/><br/>\nFor SCIM APIs <a href=\"./scim.html\">see the SCIM documentation</a>.\n<br/><br/>\nFor New, V2 APIs <a href=\"./api-v2.html\">see the V2 API documentation</a>.\n<br/><br/>\nTo use the Common Room API, or get started with the Common Room Zapier integration, you will need to create an API token.\nTo create an API token:\n<ol>\n <li>Navigate to Setting | API tokens\n <li>Create a “New Token\"\n</ol>\n\n# Authentication\n\n<!-- ReDoc-Inject: <security-definitions> -->"
x-logo:
url: /common-room-api-logo.svg
servers:
- url: https://api.commonroom.io/community/v1
description: Common Room Core API v1
tags:
- name: Topics
description: Operations related to topics
paths:
/topics/{id}:
get:
summary: Get a topic by ID
description: Retrieve a specific topic by its unique identifier.
tags:
- Topics
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The prefixed topic ID (format `tp_<number>`)
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/TopicResponse'
'400':
description: Bad Request (e.g. invalid topic ID)
content:
application/json:
schema:
$ref: '#/components/schemas/ApiV2ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'404':
description: Topic not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiV2ErrorResponse'
'429':
$ref: '#/components/responses/RateLimited'
/topics:
get:
summary: List topics
description: Retrieve a paginated list of topics, sorted alphabetically by name.
tags:
- Topics
parameters:
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 200
default: 50
description: The maximum number of topics to return per page
- name: cursor
in: query
required: false
schema:
type: string
description: Pagination cursor from a previous response
- name: query
in: query
required: false
schema:
type: string
description: Filter topics by display name prefix
- name: cols
in: query
required: false
schema:
type: string
description: 'Comma-separated list of meta columns. The meta column `recordCount`
can be requested to return the total number of matching topics in
`meta.recordCount`.
'
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/TopicList'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiV2ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'429':
$ref: '#/components/responses/RateLimited'
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
schemas:
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.
ApiV2ErrorResponse:
type: object
required:
- success
- error
properties:
success:
type: boolean
enum:
- false
error:
$ref: '#/components/schemas/ApiV2Error'
TopicList:
type: object
required:
- success
- data
- meta
properties:
success:
type: boolean
enum:
- true
data:
type: array
items:
$ref: '#/components/schemas/ApiTopic'
meta:
type: object
properties:
nextCursor:
type: string
nullable: true
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.
TopicResponse:
type: object
required:
- success
- data
properties:
success:
type: boolean
enum:
- true
data:
$ref: '#/components/schemas/ApiTopic'
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
ApiTopic:
type: object
required:
- id
- name
properties:
id:
type: string
description: Prefixed topic ID (format `tp_<number>`)
name:
type: string
description: The topic's display name
responses:
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
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"