classifier-dev Subscribe API

openapi: 3.2.0
info:
  title: classifier.dev Subscribe API
  version: 1.0.0
  summary: Zero-shot text classification with calibrated confidence. Free without a key; paid plans raise rate limits 10-100x.
  description: 'Send text and a list of labels, receive the label that fits, a calibrated confidence and a score per label. Up to 1,000 texts per request, ~1s. Tiers: fast (default) and smart, which re-asks answers below 0.7 confidence of a fast reasoning model. Free limits are per IP and counted in classifications: 3,000/min and 20,000/day on fast, 200/min and 2,000/day on smart. Benchmarks: https://classifier.dev/benchmark


    Authentication: optional for classification. Pro ($20/month) workspaces provide fast 30,000/min and 200,000/day, smart 2,000/min and 20,000/day shared across workspace keys and agents. Partner keys remain supported (see https://classifier.dev/auth.md).


    Versioning: the current major is v1, addressed as POST /v1/classify; POST / is an alias that tracks the current major. Response shapes are additive within a major (fields are added, never renamed or removed). Every response carries an x-api-version header. A breaking change ships as /v2 beside /v1, and /v1 then carries Deprecation and Sunset headers (RFC 9745 / RFC 8594) for at least six months before removal.


    Rate limits: RateLimit-Limit and RateLimit-Policy (IETF draft-ietf-httpapi-ratelimit-headers) on every classification response, RateLimit-Remaining once the limiter has been consulted (every 200 and 429), Retry-After on 429s. Idempotency: synchronous paid requests reject replayed keys. Whole-document jobs accept an optional UUID Idempotency-Key and return the same job on retry without charging again.


    Errors: classification failures return {error, code}; workspace authorization and billing errors return {error}. See components.schemas.Error for classification codes. The two GET forms answer plain text (`error:`, `usage:`, `try:` lines) unless ?verbose=1 or Accept: application/json asks for the JSON object.


    MCP: the same capability as tools at https://classifier.dev/mcp (Streamable HTTP, no auth), documented at https://classifier.dev/mcp-setup. Batch: the inputs array is the batch operation — up to 1,000 texts per request; POST /v1/classify/batch is an alias for callers that look for one.'
  contact:
    name: Michael Ryaboy
    url: https://cal.com/michaelsf/coffee
    email: contact@classifier.dev
  license:
    name: MIT
    url: https://github.com/mrmps/classifier-dev/blob/main/LICENSE
  termsOfService: https://classifier.dev/terms
  x-api-versioning:
    scheme: url-path
    current: v1
    aliases:
    - /
    - /v1/classify
    - /v1/classify/batch
    deprecationSignal: Deprecation and Sunset response headers, at least 180 days notice
    changelog: https://github.com/mrmps/classifier-dev/commits/main
  x-mcp:
    url: https://classifier.dev/mcp
    docs: https://classifier.dev/mcp/docs
    card: https://classifier.dev/.well-known/mcp/server-card.json
servers:
- url: https://classifier.dev
security:
- {}
- partnerKey: []
tags:
- name: Subscribe
paths:
  /subscribe:
    post:
      operationId: subscribeToUpdates
      summary: Subscribe a human or agent inbox to product updates
      description: Use your own email address, or one whose owner explicitly requested updates. No API key or browser is required. Check the inbox and POST the emailed token to /subscribe/confirm before updates start. Tokens expire within 24 hours; repeated requests within the same clock hour send at most one email. Addresses are trimmed and lowercased. Signup does not add an active subscriber. Existing unsubscribes are preserved. One email when a roadmap item ships; reply to unsubscribe. Limited to 5 requests/minute and 50/day per IP.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  maxLength: 254
                  description: An email address for an inbox you control or have explicit permission to subscribe.
                  example: agent@example.com
                wants:
                  type: array
                  uniqueItems: true
                  items:
                    type: string
                    enum:
                    - private
                    - faster
                    - dedicated
                    - trained
                    - api
                    - accuracy
                  description: 'Optional. The roadmap items the subscriber would use first: private (private inference), faster (faster inference), dedicated (dedicated endpoints), trained (trained endpoints), api (a self-serve api), accuracy (better classification). Unknown keys are ignored. The list rides in the confirmation token and is stored on confirmation; a later confirmation that names some replaces the earlier choice, one that names none keeps it.'
                  example:
                  - faster
                desired_latency_ms:
                  type: integer
                  minimum: 1
                  maximum: 60000
                  description: Required when wants includes faster; ignored otherwise. The desired end-to-end inference latency in milliseconds.
                  example: 100
      responses:
        '202':
          description: Confirmation email accepted by the mail provider. The address is not yet subscribed.
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - status
                properties:
                  ok:
                    const: true
                  status:
                    const: pending_confirmation
                  wants:
                    type: array
                    items:
                      type: string
                    description: The roadmap keys that were accepted, in roadmap order.
                  desired_latency_ms:
                    type: integer
                    description: Returned when faster inference was selected.
                example:
                  ok: true
                  status: pending_confirmation
                  wants:
                  - faster
                  desired_latency_ms: 100
        '400':
          description: Missing or invalid email address.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '429':
          description: Too many signups; wait Retry-After seconds before retrying.
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '503':
          description: Confirmation email unavailable; retry shortly.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
      tags:
      - Subscribe
  /subscribe/confirm:
    post:
      operationId: confirmSubscription
      summary: Confirm mailbox ownership using the emailed token
      description: Submit the token from the confirmation email. Invalid or expired tokens cannot subscribe an address. Repeated confirmation is safe and never undoes an unsubscribe. GET renders a confirmation form without changing subscription state.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - token
              properties:
                token:
                  type: string
                  maxLength: 1500
      responses:
        '200':
          description: Mailbox confirmed; existing unsubscribe preferences remain in effect.
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - status
                properties:
                  ok:
                    const: true
                  status:
                    const: confirmed
                  wants:
                    type: array
                    items:
                      type: string
                    description: The roadmap keys recorded with the confirmation.
                  desired_latency_ms:
                    type: integer
                    description: Returned when faster inference was selected.
        '400':
          description: Invalid or expired token. Subscribe again for a fresh email.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '503':
          description: Confirmation storage unavailable. Retry the same token shortly.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
      tags:
      - Subscribe
components:
  securitySchemes:
    accountKey:
      type: http
      scheme: bearer
      description: Workspace API key (classifier_agent_...) managed at /app/keys. Required for account reads; optional on classification and TypeSafe-compatible endpoints to use workspace quota and credits.
    partnerKey:
      type: http
      scheme: bearer
      description: Optional for classification. Workspace keys (classifier_agent_...) use the workspace balance and quotas; Pro raises rate limits 10x and Scale 100x. Partner keys have separately arranged access. See https://classifier.dev/auth.md.
externalDocs:
  description: Developer guide
  url: https://classifier.dev/developers