Copper Financial Tags API

openapi: 3.2.0
info:
  title: Copper CRM Read-Only Tags API
  description: Read-only operations for Copper CRM API - optimized for ChatGPT integration
  version: 1.0.0
  contact:
    name: Copper Developer Support
    url: https://developer.copper.com/
    email: support@copper.com
servers:
- url: https://api.copper.com/developer_api/v1
  description: Copper API Production Server
security:
- bearerAuth: []
tags:
- name: Tags
  description: Tag management operations
paths:
  /tags:
    get:
      tags:
      - Tags
      summary: List all tags
      description: Retrieve a list of all tags and their entity usage counts. When tag_names_only=true, returns an array of strings instead of tag objects.
      operationId: listTags
      parameters:
      - name: sort_by
        in: query
        required: false
        description: Can sort by the tag name or count (the total number of times it is used). Only applicable when tag_names_only=false, otherwise it is auto-sorted by name.
        schema:
          type: string
          enum:
          - name
          - count
          default: name
      - name: tag_names_only
        in: query
        required: false
        description: When true, only a list of tag names is provided with no entity usage counts (returns array of strings). When false or omitted, returns full tag objects with counts.
        schema:
          type: boolean
          default: false
      - name: last_tag_value
        in: query
        required: false
        description: Requires tag_names_only=true. Allows you to provide a tag value to get all the tags that occur after it in the alphabetically-sorted list. The max page size is 10000 so you can use this to paginate through large tag lists.
        schema:
          type: string
      responses:
        '200':
          description: 'Tags retrieved successfully. Response format depends on tag_names_only parameter: array of Tag objects (default) or array of strings (when tag_names_only=true).'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                oneOf:
                - type: array
                  description: Array of tag objects with usage counts (default when tag_names_only=false or omitted)
                  items:
                    $ref: '#/components/schemas/Tag'
                - type: array
                  description: Array of tag name strings (when tag_names_only=true)
                  items:
                    type: string
                    example: Apples
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  headers:
    Retry-After:
      description: The number of seconds to wait before making a new request after hitting the rate limit
      schema:
        type: integer
        example: 60
    X-RateLimit-Reset:
      description: The time at which the current rate limit window resets, in UTC epoch seconds
      schema:
        type: integer
        example: 1640995200
    X-RateLimit-Remaining:
      description: The number of requests remaining in the current time window
      schema:
        type: integer
        example: 179
    X-RateLimit-Limit:
      description: The maximum number of requests allowed in the current time window
      schema:
        type: integer
        example: 180
  responses:
    InternalServerError:
      description: Internal Server Error - An unexpected error occurred
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - Authentication credentials were missing or incorrect
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request - The request was invalid or cannot be served
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: RATE_LIMIT_EXCEEDED
            message:
              type: string
              description: Human-readable error message
              example: You have exceeded your rate limit of 180 requests per minute
            details:
              type: object
              description: Additional error details
              additionalProperties: true
          required:
          - code
          - message
      required:
      - error
    Tag:
      type: object
      description: A tag is a string that can be associated to any of the 6 core entities in Copper (Leads, People, Companies, Opportunities, Tasks, Projects)
      properties:
        name:
          type: string
          description: The name of the tag
          example: Apples
        count:
          type: integer
          description: The total number of entities the tag is associated to
          example: 5
        count_people:
          type: integer
          description: The number of people the tag is associated to
          example: 1
        count_leads:
          type: integer
          description: The number of leads the tag is associated to
          example: 1
        count_companies:
          type: integer
          description: The number of companies the tag is associated to
          example: 1
        count_opportunities:
          type: integer
          description: The number of opportunities the tag is associated to
          example: 1
        count_projects:
          type: integer
          description: The number of projects the tag is associated to
          example: 1
        count_tasks:
          type: integer
          description: The number of tasks the tag is associated to
          example: 0
      required:
      - name
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Copper API key for authentication. Get your API key from your Copper account settings.
x-rate-limit:
  description: Copper API rate limiting information
  general:
    limit: 180
    period: minute
    description: Maximum of 180 requests per minute for general API calls
  bulk:
    limit: 3
    period: second
    description: Maximum of 3 requests per second for bulk operations