Audioscrape Account API

openapi: 3.2.0
info:
  title: Audioscrape Com Account API
  version: '2026-05-16'
  contact:
    name: Audioscrape
    url: https://www.audioscrape.com
    email: lukas@audioscrape.com
  license:
    name: ''
  description: 'Operations tagged Account across 2 of this provider''s published API definitions: audioscrape-com-openapi.json, audioscrape-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://www.audioscrape.com
  description: Production
tags:
- name: Account
  description: 'Current-user introspection: plan, limits, usage'
paths:
  /api/me:
    get:
      tags:
      - Account
      summary: Current user, plan, and key info
      description: Returns the authenticated user, their current plan + per-resource limits, the API key that authenticated the request (if any), and the effective dated API version. Use this as the first call in any integration to verify credentials and discover capabilities.
      operationId: get_me
      responses:
        '200':
          description: Current user, plan, limits, key info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - BearerAuth: []
    servers:
    - url: https://www.audioscrape.com
      description: Production
  /api/me/usage:
    get:
      tags:
      - Account
      summary: Current usage and limits
      description: Returns this calendar month's usage counters (searches, semantic searches, data calls, keyword alerts) alongside the plan's configured limits. Use it to handle 429 responses proactively — check usage before a heavy burst and back off if you're close to a cap.
      operationId: get_me_usage
      responses:
        '200':
          description: Usage counters vs plan limits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - BearerAuth: []
    servers:
    - url: https://www.audioscrape.com
      description: Production
components:
  schemas:
    MeWorkspace:
      type: object
      required:
      - id
      - slug
      - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        role:
          type:
          - string
          - 'null'
          description: 'Your role in this workspace (`owner`, `admin`, or `member`). `null`

            when the authenticated user has no membership row here.'
        slug:
          type: string
          description: Stable URL slug, e.g. `audioscrape`.
    ApiErrorBody:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Stable machine-readable error code (UPPERCASE_SNAKE_CASE).
          example: SEARCH_LIMIT_EXCEEDED
        message:
          type: string
          description: Human-readable error message.
          example: Monthly search limit reached
        usage:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/UsageInfo'
            description: Present on rate-limit / quota errors. Omitted otherwise.
    UsageResponse:
      type: object
      required:
      - period
      - searches
      - semantic_searches
      - data_calls
      - keyword_alerts
      properties:
        data_calls:
          $ref: '#/components/schemas/UsageCounter'
        keyword_alerts:
          $ref: '#/components/schemas/UsageCounter'
        period:
          type: string
          description: Calendar month the usage counters cover (UTC, format `YYYY-MM`).
        searches:
          $ref: '#/components/schemas/UsageCounter'
        semantic_searches:
          $ref: '#/components/schemas/UsageCounter'
    UsageInfo:
      type: object
      required:
      - current
      - limit
      properties:
        current:
          type: integer
          format: int64
          description: Current usage value (e.g., calls consumed this period).
        limit:
          type: integer
          format: int64
          description: Configured limit for the period.
    MeUser:
      type: object
      required:
      - id
      - email
      properties:
        email:
          type: string
        id:
          type: integer
          format: int64
        member_since:
          type:
          - string
          - 'null'
          description: ISO-8601 UTC timestamp of account creation.
        name:
          type:
          - string
          - 'null'
    MePlan:
      type: object
      required:
      - name
      - limits
      properties:
        limits:
          $ref: '#/components/schemas/PlanLimitsResponse'
        name:
          type: string
          description: 'Plan slug: `free`, `starter`, `basic`, `pro`, `enterprise`.'
    UsageCounter:
      type: object
      required:
      - used
      properties:
        limit:
          type:
          - integer
          - 'null'
          format: int64
          description: Configured plan limit for the period. `null` if unlimited.
        used:
          type: integer
          format: int64
          description: Count used in the current period.
    MeApiKey:
      type: object
      required:
      - id
      - key_name
      - pinned_version
      properties:
        id:
          type: integer
          format: int64
        key_name:
          type: string
        pinned_version:
          type: string
          description: Dated API version the key is pinned to (see `Audioscrape-Version`).
    PlanLimitsResponse:
      type: object
      required:
      - webhooks_enabled
      - max_api_keys
      properties:
        data_calls_per_month:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Monthly data-API call limit (podcasts, episodes, persons, entities,

            charts, trending). `null` means unlimited; `0` means disabled.'
        keyword_alerts:
          type:
          - integer
          - 'null'
          format: int64
          description: Maximum number of keyword alerts a user can create. `null` = unlimited.
        max_api_keys:
          type: integer
          format: int64
        searches_per_month:
          type:
          - integer
          - 'null'
          format: int64
          description: Monthly text-search limit. `null` means unlimited.
        semantic_searches_per_month:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Monthly semantic / hybrid search limit. `null` means unlimited;

            `0` means the feature is disabled on this plan.'
        storage_mb:
          type:
          - integer
          - 'null'
          format: int64
          description: Storage limit for private uploads, in megabytes. `null` = unlimited.
        transcription_minutes_per_month:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Monthly transcription quota for private uploads (in audio minutes).

            `null` = unlimited; `0` = uploads disabled.'
        webhooks_enabled:
          type: boolean
          description: Whether webhook delivery is enabled for keyword alerts on this plan.
    MeResponse:
      type: object
      required:
      - user
      - workspace
      - plan
      - api_version
      properties:
        api_key:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/MeApiKey'
            description: 'API key the request was authenticated with. `null` when authenticated

              via session cookie (e.g. logged-in browser hitting the API).'
        api_version:
          type: string
          description: 'Effective dated API version this request was evaluated against, per the

            `Audioscrape-Version` header / `api_keys.pinned_version` resolution.'
        plan:
          $ref: '#/components/schemas/MePlan'
        user:
          $ref: '#/components/schemas/MeUser'
        workspace:
          $ref: '#/components/schemas/MeWorkspace'
          description: 'Workspace this request is scoped to (resolved from the API key or the

            session''s active workspace). List all your workspaces at `/api/workspaces`.'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key, format `sk_<base64(32 random bytes)>`
      description: 'Workspace-scoped API key. Pass as `Authorization: Bearer <key>`. The `?api_key=<key>` query parameter is deprecated: a key in a URL ends up in browser history, proxy logs and Referer headers.'
x-refined-from:
- audioscrape-com-openapi.json
- audioscrape-com-openapi.json