Common Room Tags API

The Tags API from Common Room — 2 operation(s) for tags.

Documentation GitHub OpenAPI

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

POST /tags Create a new tag · Add Tag #

Ask an LLM

“How do I create a new tag for labeling contacts?”

“What happens if I add a tag whose name already exists?”

Tell an agent

Create a tag named {name}.

Add a new tag {name} described as {description}.

GET /tags/{id} Look up a single tag by ID · Get Tag #

Ask an LLM

“Which name and description belong to a specific tag ID?”

“Can I fetch the details of one tag if I know its ID?”

Tell an agent

Get the details of tag {id}.

Look up what tag {id} is called.

POST /tags/{id} Rename or redescribe an existing tag · Update Tag #

Ask an LLM

“How do I rename a tag that already exists?”

“Can I restore a deleted tag by updating it?”

Tell an agent

Rename tag {id} to {name}.

Change tag {id} to name {name} with description {description}.

DELETE /tags/{id} Delete a tag everywhere it is used · Delete Tag #

Ask an LLM

“Will deleting a tag remove it from every contact and activity it was added to?”

“Could removing a tag break alerts or workflows that rely on it?”

Tell an agent destructive · confirm first

Delete tag {id}.

Remove tag {id} from everywhere it's applied.

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-tags-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

openapi: 3.2.0
info:
  title: Common Room Tags API
  x-logo:
    url: /common-room-api-logo.svg
  version: '1.0'
  description: 'Operations tagged Tags 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: Tags
paths:
  /tags:
    get:
      description: Returns the list of user defined tags
      summary: List Tags
      tags:
      - Tags
      operationId: listTags
      responses:
        '200':
          description: List of non-deleted user defined tags
          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:
                  labels:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiTag'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      description: Creates a new tag if no matching tag already exists, otherwise returns the existing tag.
      summary: Add Tag
      tags:
      - Tags
      operationId: createTag
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiTagCreationProperties'
      responses:
        '200':
          description: Tag 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/ApiTag'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://api.commonroom.io/community/v1
      description: Common Room Core API v1
  /tags/{id}:
    get:
      description: Returns the tag for a given id
      summary: Get Tag
      tags:
      - Tags
      operationId: getTag
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: The Tag ID to fetch
      responses:
        '200':
          description: Matching tag
          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/ApiTag'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '404':
          description: Tag 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'
    post:
      description: 'Updates the name or description for a given id.


        If the tag is deleted, it will be undeleted on update.'
      summary: Update Tag
      tags:
      - Tags
      operationId: updateTag
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: The Tag ID to fetch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiTagUpdateProperties'
      responses:
        '200':
          description: Updated tag
          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/ApiTag'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '404':
          description: Tag 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'
    delete:
      description: 'Deletes the tag for a given id.


        Deleting the tag will remove it from everywhere you added it, and might break alerts or workflows that depend on it.'
      summary: Delete Tag
      tags:
      - Tags
      operationId: deleteTag
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: The Tag ID to fetch
      responses:
        '200':
          description: OK - Tag deleted
          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: Tag 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'
    servers:
    - url: https://api.commonroom.io/community/v1
      description: Common Room Core API v1
components:
  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
    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
  schemas:
    ApiTagUpdateProperties:
      type: object
      properties:
        name:
          description: Name of the tag
          type: string
        description:
          description: Optional description of the tag
          type:
          - string
          - 'null'
      required:
      - name
    ApiTag:
      allOf:
      - $ref: '#/components/schemas/ApiTagCreationProperties'
      - type: object
        properties:
          id:
            description: Unique identifier for this tag
            type: string
          createdAt:
            description: The date-time the tag was created in ISO8601 format
            type: string
            format: date-time
          deletedAt:
            description: The date-time the tag was deleted in ISO8601 format
            type:
            - string
            - 'null'
            format: date-time
      required:
      - id
      - createdAt
    ApiTagCreationProperties:
      allOf:
      - $ref: '#/components/schemas/ApiTagUpdateProperties'
      - type: object
        properties:
          entityTypes:
            description: The list of entity types the tag may be assigned to
            type: array
            items:
              type: string
              enum:
              - member
              - activity
              - company
      required:
      - name
      - entityTypes
    TagList:
      type: object
      required:
      - success
      - data
      - meta
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          type: array
          items:
            $ref: '#/components/schemas/ApiTag_2'
        meta:
          type: object
          required:
          - nextCursor
          properties:
            nextCursor:
              type:
              - string
              - 'null'
              description: Cursor for pagination; pass as the `cursor` query parameter to fetch the next page.
    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
    ApiV2ErrorResponse:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          $ref: '#/components/schemas/ApiV2Error'
    TagResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          $ref: '#/components/schemas/ApiTag_2'
    ApiTag_2:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Prefixed tag ID (format `l_<number>`)
        name:
          type: string
          description: The tag's display name
        description:
          type:
          - string
          - 'null'
          description: Human-readable description of the tag
        entityTypes:
          type: array
          items:
            type: string
            enum:
            - contact
            - organization
            - activity
          description: Entity types this tag can be applied to
    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.
  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
  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

Common Room Tags API

Operations 5

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification