classifier-dev Account API

openapi: 3.2.0
info:
  title: classifier.dev Account 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: Account
  description: Workspace balance and usage; requires a workspace API key and enabled account access.
paths:
  /v1/account/balance:
    get:
      operationId: getAccountBalance
      summary: Read exact available and reserved workspace funds
      description: No query parameters. Amounts are USD decimal strings with five fractional digits. Available funds exclude pending reservations. Requires an active workspace API key. Responses are private and not cached.
      tags:
      - Account
      security:
      - accountKey: []
      responses:
        '200':
          description: Exact ledger snapshot
          content:
            application/json:
              schema:
                type: object
                required:
                - currency
                - available
                - reserved
                - exact
                properties:
                  currency:
                    const: USD
                  available:
                    type: string
                    pattern: ^[0-9]+\.[0-9]{5}$
                  reserved:
                    type: string
                    pattern: ^[0-9]+\.[0-9]{5}$
                  exact:
                    const: true
        '400':
          description: Invalid or duplicate query parameter, or unsupported date range.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '401':
          description: Missing, invalid, paused, revoked, or local-only workspace API key.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '404':
          description: Workspace no longer exists.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '405':
          description: Only GET is supported.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '503':
          description: Account access or analytics is not enabled or temporarily unavailable.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
  /v1/account/usage/summary:
    get:
      operationId: getAccountUsageSummary
      summary: Read workspace usage totals
      description: Aggregates the selected period. Analytics may be delayed or sampled; use /v1/account/balance for exact spendable funds. Workspace is derived from the API key; an account ID cannot be supplied. Responses are private and not cached.
      tags:
      - Account
      security:
      - accountKey: []
      parameters:
      - name: from
        schema:
          type: string
          format: date-time
        description: Inclusive start, within the last 90 days. Defaults to 30 days ago.
        in: query
        required: false
      - name: to
        schema:
          type: string
          format: date-time
        description: Exclusive end. Defaults to now.
        in: query
        required: false
      - name: key_id
        schema:
          type: string
        description: Filter by a workspace API key ID.
        in: query
        required: false
      - name: agent_id
        schema:
          type: string
        description: Filter by an agent identifier recorded with the request.
        in: query
        required: false
      - name: tier
        schema:
          type: string
          enum:
          - fast
          - smart
        in: query
        required: false
      - name: source
        schema:
          type: string
          enum:
          - api
          - mcp
        in: query
        required: false
      - name: status
        schema:
          type: string
          enum:
          - success
          - error
        in: query
        required: false
      responses:
        '200':
          description: Workspace analytics
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties:
                        type:
                        - string
                        - number
                        - 'null'
                    description: Summary/timeseries/breakdown rows include requests, items, token and cost totals, missing-value counters, latencyMs, errors, sampleInterval and latestEventAt. Timeseries adds bucket; breakdown adds dimension. Activity rows include requestId, keyId, agentId, source, tier, model, status and timestamp. Content is not returned.
                  meta:
                    type: object
                    required:
                    - queriedAt
                    - latestEventAt
                    - sampled
                    - exact
                    - retentionDays
                    properties:
                      queriedAt:
                        type: string
                        format: date-time
                      latestEventAt:
                        type:
                        - string
                        - 'null'
                      sampled:
                        type: boolean
                      exact:
                        const: false
                      retentionDays:
                        const: 90
        '400':
          description: Invalid or duplicate query parameter, or unsupported date range.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '401':
          description: Missing, invalid, paused, revoked, or local-only workspace API key.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '405':
          description: Only GET is supported.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '429':
          description: Analytics query budget exhausted. Your balance is unaffected.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '503':
          description: Account access or analytics is not enabled or temporarily unavailable.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
  /v1/account/usage/timeseries:
    get:
      operationId: getAccountUsageTimeseries
      summary: Read hourly or daily workspace usage
      description: Returns at most 745 buckets. Hourly ranges cannot exceed 31 days. Analytics may be delayed or sampled; use /v1/account/balance for exact spendable funds. Workspace is derived from the API key; an account ID cannot be supplied. Responses are private and not cached.
      tags:
      - Account
      security:
      - accountKey: []
      parameters:
      - name: from
        schema:
          type: string
          format: date-time
        description: Inclusive start, within the last 90 days. Defaults to 30 days ago.
        in: query
        required: false
      - name: to
        schema:
          type: string
          format: date-time
        description: Exclusive end. Defaults to now.
        in: query
        required: false
      - name: key_id
        schema:
          type: string
        description: Filter by a workspace API key ID.
        in: query
        required: false
      - name: agent_id
        schema:
          type: string
        description: Filter by an agent identifier recorded with the request.
        in: query
        required: false
      - name: tier
        schema:
          type: string
          enum:
          - fast
          - smart
        in: query
        required: false
      - name: source
        schema:
          type: string
          enum:
          - api
          - mcp
        in: query
        required: false
      - name: status
        schema:
          type: string
          enum:
          - success
          - error
        in: query
        required: false
      - name: interval
        in: query
        required: false
        schema:
          type: string
          enum:
          - hour
          - day
          default: day
      responses:
        '200':
          description: Workspace analytics
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties:
                        type:
                        - string
                        - number
                        - 'null'
                    description: Summary/timeseries/breakdown rows include requests, items, token and cost totals, missing-value counters, latencyMs, errors, sampleInterval and latestEventAt. Timeseries adds bucket; breakdown adds dimension. Activity rows include requestId, keyId, agentId, source, tier, model, status and timestamp. Content is not returned.
                  meta:
                    type: object
                    required:
                    - queriedAt
                    - latestEventAt
                    - sampled
                    - exact
                    - retentionDays
                    properties:
                      queriedAt:
                        type: string
                        format: date-time
                      latestEventAt:
                        type:
                        - string
                        - 'null'
                      sampled:
                        type: boolean
                      exact:
                        const: false
                      retentionDays:
                        const: 90
        '400':
          description: Invalid or duplicate query parameter, or unsupported date range.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '401':
          description: Missing, invalid, paused, revoked, or local-only workspace API key.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '405':
          description: Only GET is supported.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '429':
          description: Analytics query budget exhausted. Your balance is unaffected.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '503':
          description: Account access or analytics is not enabled or temporarily unavailable.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
  /v1/account/usage/breakdown:
    get:
      operationId: getAccountUsageBreakdown
      summary: Compare workspace usage by key, agent, tier or model
      description: Returns the top 50 groups ordered by requests. Analytics may be delayed or sampled; use /v1/account/balance for exact spendable funds. Workspace is derived from the API key; an account ID cannot be supplied. Responses are private and not cached.
      tags:
      - Account
      security:
      - accountKey: []
      parameters:
      - name: from
        schema:
          type: string
          format: date-time
        description: Inclusive start, within the last 90 days. Defaults to 30 days ago.
        in: query
        required: false
      - name: to
        schema:
          type: string
          format: date-time
        description: Exclusive end. Defaults to now.
        in: query
        required: false
      - name: key_id
        schema:
          type: string
        description: Filter by a workspace API key ID.
        in: query
        required: false
      - name: agent_id
        schema:
          type: string
        description: Filter by an agent identifier recorded with the request.
        in: query
        required: false
      - name: tier
        schema:
          type: string
          enum:
          - fast
          - smart
        in: query
        required: false
      - name: source
        schema:
          type: string
          enum:
          - api
          - mcp
        in: query
        required: false
      - name: status
        schema:
          type: string
          enum:
          - success
          - error
        in: query
        required: false
      - name: group_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - key
          - agent
          - tier
          - model
          default: key
      responses:
        '200':
          description: Workspace analytics
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties:
                        type:
                        - string
                        - number
                        - 'null'
                    description: Summary/timeseries/breakdown rows include requests, items, token and cost totals, missing-value counters, latencyMs, errors, sampleInterval and latestEventAt. Timeseries adds bucket; breakdown adds dimension. Activity rows include requestId, keyId, agentId, source, tier, model, status and timestamp. Content is not returned.
                  meta:
                    type: object
                    required:
                    - queriedAt
                    - latestEventAt
                    - sampled
                    - exact
                    - retentionDays
                    properties:
                      queriedAt:
                        type: string
                        format: date-time
                      latestEventAt:
                        type:
                        - string
                        - 'null'
                      sampled:
                        type: boolean
                      exact:
                        const: false
                      retentionDays:
                        const: 90
        '400':
          description: Invalid or duplicate query parameter, or unsupported date range.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '401':
          description: Missing, invalid, paused, revoked, or local-only workspace API key.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '405':
          description: Only GET is supported.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '429':
          description: Analytics query budget exhausted. Your balance is unaffected.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '503':
          description: Account access or analytics is not enabled or temporarily unavailable.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
  /v1/account/activity:
    get:
      operationId: getAccountActivity
      summary: Read recent workspace request metadata
      description: Returns at most 100 recent events, newest first. Sampled activity is not an exhaustive audit log. Analytics may be delayed or sampled; use /v1/account/balance for exact spendable funds. Workspace is derived from the API key; an account ID cannot be supplied. Responses are private and not cached.
      tags:
      - Account
      security:
      - accountKey: []
      parameters:
      - name: from
        schema:
          type: string
          format: date-time
        description: Inclusive start, within the last 90 days. Defaults to 30 days ago.
        in: query
        required: false
      - name: to
        schema:
          type: string
          format: date-time
        description: Exclusive end. Defaults to now.
        in: query
        required: false
      - name: key_id
        schema:
          type: string
        description: Filter by a workspace API key ID.
        in: query
        required: false
      - name: agent_id
        schema:
          type: string
        description: Filter by an agent identifier recorded with the request.
        in: query
        required: false
      - name: tier
        schema:
          type: string
          enum:
          - fast
          - smart
        in: query
        required: false
      - name: source
        schema:
          type: string
          enum:
          - api
          - mcp
        in: query
        required: false
      - name: status
        schema:
          type: string
          enum:
          - success
          - error
        in: query
        required: false
      responses:
        '200':
          description: Workspace analytics
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties:
                        type:
                        - string
                        - number
                        - 'null'
                    description: Summary/timeseries/breakdown rows include requests, items, token and cost totals, missing-value counters, latencyMs, errors, sampleInterval and latestEventAt. Timeseries adds bucket; breakdown adds dimension. Activity rows include requestId, keyId, agentId, source, tier, model, status and timestamp. Content is not returned.
                  meta:
                    type: object
                    required:
                    - queriedAt
                    - latestEventAt
                    - sampled
                    - exact
                    - retentionDays
                    properties:
                      queriedAt:
                        type: string
                        format: date-time
                      latestEventAt:
                        type:
                        - string
                        - 'null'
                      sampled:
                        type: boolean
                      exact:
                        const: false
                      retentionDays:
                        const: 90
        '400':
          description: Invalid or duplicate query parameter, or unsupported date range.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '401':
          description: Missing, invalid, paused, revoked, or local-only workspace API key.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '405':
          description: Only GET is supported.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '429':
          description: Analytics query budget exhausted. Your balance is unaffected.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '503':
          description: Account access or analytics is not enabled or temporarily unavailable.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
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