The Token Company Compression API

openapi: 3.1.0
info:
  title: The Token Company Compression API
  version: '1.0'
  description: LLM input compression middleware. One API call removes low-signal tokens from a prompt, a chat conversation, or web-search results before they reach a language model, cutting cost and latency while preserving output quality. Compression is performed by the bear family of models (bear-2 latest, bear-1.2 / bear-1.1 / bear-1 previous generations).
  x-provenance:
    generated: '2026-07-21'
    method: generated
    note: Faithfully reconstructed from the official Python SDK source (github.com/TheTokenCompany/the-token-company-python) and the public documentation at https://thetokencompany.com/docs. The provider does not publish an OpenAPI document; the API itself is invite-only. No behavior, field, endpoint, or error was invented.
  contact:
    name: The Token Company
    url: https://thetokencompany.com/contact
  license:
    name: Proprietary
servers:
- url: https://api.thetokencompany.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Compression
  description: Prompt and conversation compression
paths:
  /v1/compress:
    post:
      operationId: compressPrompt
      summary: Compress a prompt
      description: Compress a single block of prompt text. Returns the compressed output plus token counts before and after compression.
      tags:
      - Compression
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompressRequest'
      responses:
        '200':
          description: Compressed text and token metrics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompressResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '413':
          $ref: '#/components/responses/RequestTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /v1/chat/compress:
    post:
      operationId: compressChat
      summary: Compress a chat conversation
      description: Compress a whole OpenAI- or Anthropic-format message array in a single request. Assistant messages pass through unchanged so the downstream provider's KV cache stays warm; re-sent history is served from a server-side cache.
      tags:
      - Compression
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompressRequest'
      responses:
        '200':
          description: Compressed message array and token metrics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompressResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '413':
          $ref: '#/components/responses/RequestTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    RateLimited:
      description: Too many requests (SDK RateLimitError).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: Insufficient balance or exceeded debt limit (SDK PaymentRequiredError).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Unexpected server error (SDK APIError, 5xx).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RequestTooLarge:
      description: Payload exceeds size limits (SDK RequestTooLargeError).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or missing API key (SDK AuthenticationError).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidRequest:
      description: Bad parameters (SDK InvalidRequestError).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CompressResponse:
      type: object
      required:
      - output
      - output_tokens
      - original_input_tokens
      properties:
        output:
          type: string
          description: The compressed text.
        output_tokens:
          type: integer
          description: Token count after compression.
        original_input_tokens:
          type: integer
          description: Token count before compression.
    CompressRequest:
      type: object
      required:
      - text
      properties:
        text:
          type: string
          description: The prompt or content to compress. Wrap spans in <ttc_safe>...</ttc_safe> to exclude them.
        model:
          $ref: '#/components/schemas/Model'
        aggressiveness:
          type: number
          format: float
          minimum: 0.0
          maximum: 1.0
          default: 0.2
          description: Compression intensity, 0.0 (lightest) to 1.0 (most aggressive).
        app_id:
          type: string
          maxLength: 255
          description: Optional application identifier for usage tracking.
    ChatCompressResponse:
      type: object
      required:
      - messages
      - original_input_tokens
      - output_tokens
      properties:
        messages:
          type: array
          items:
            type: object
          description: The compressed message array.
        system:
          description: The compressed system prompt, when supplied.
        original_input_tokens:
          type: integer
        output_tokens:
          type: integer
        cache_hits:
          type: integer
          description: Messages served from the server-side cache.
        cache_misses:
          type: integer
        compression_time:
          type: number
          format: float
          description: Server compression time in seconds.
    ChatCompressRequest:
      type: object
      required:
      - messages
      properties:
        messages:
          type: array
          items:
            type: object
          description: OpenAI- or Anthropic-format message array.
        model:
          $ref: '#/components/schemas/Model'
        fmt:
          type: string
          enum:
          - openai
          - anthropic
          default: openai
          description: Message-format dialect controlling block walking.
        aggressiveness:
          oneOf:
          - type: number
            format: float
            minimum: 0.0
            maximum: 1.0
          - type: object
            additionalProperties:
              type: number
              format: float
            description: Per-role aggressiveness map keyed by role.
          default: 0.2
        system:
          description: Anthropic top-level system prompt (string or block array).
        strip_server_tool_results:
          type: boolean
          default: false
          description: Drop Anthropic server tool-result blocks.
        skip_tool_use_ids:
          type: array
          items:
            type: string
          description: Anthropic tool_result ids to leave uncompressed.
        app_id:
          type: string
          maxLength: 255
    Model:
      type: string
      enum:
      - bear-2
      - bear-1.2
      - bear-1.1
      - bear-1
      default: bear-2
      description: Compression model. bear-2 is the latest and recommended.
    Error:
      type: object
      description: Error envelope; SDKs map the HTTP status to a typed exception.
      properties:
        message:
          type: string
        status_code:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key issued by The Token Company, sent as `Authorization: Bearer ttc-...`.'