Audioscrape API Keys API

openapi: 3.2.0
info:
  title: Audioscrape Com API Keys API
  version: '2026-05-16'
  contact:
    name: Audioscrape
    url: https://www.audioscrape.com
    email: lukas@audioscrape.com
  license:
    name: ''
  description: 'Operations tagged API Keys 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: API Keys
  description: Create and manage API keys for programmatic access
paths:
  /api/keys:
    get:
      tags:
      - API Keys
      summary: List your API keys
      description: 'Returns all API keys belonging to the calling user. `key_value` is `null` on every entry — only the display `key_prefix` is recoverable after creation. To get a fresh raw value for a key, rotate it: `POST /api/keys/{id}/rotate`.


        Accepts either a session cookie or an existing API key as auth.'
      operationId: list_api_keys
      responses:
        '200':
          description: All API keys for the calling user
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKey'
        '401':
          description: Missing or invalid session / key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - BearerAuth: []
    post:
      tags:
      - API Keys
      summary: Create a new API key
      description: 'Generates a new workspace-scoped API key. The full `key_value` is returned **only** in this response — Audioscrape stores a SHA-256 hash and the prefix only, so save the raw key immediately on the client side. If you lose it, rotate the key.


        Accepts either a session cookie or an existing API key as auth.'
      operationId: create_api_key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKey'
        required: true
      responses:
        '201':
          description: Key created. `key_value` is shown in full here for the only time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          description: Missing or invalid session / key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - BearerAuth: []
    servers:
    - url: https://www.audioscrape.com
      description: Production
  /api/keys/{id}:
    delete:
      tags:
      - API Keys
      summary: Delete an API key
      description: 'Revokes the key immediately. Any in-flight requests using the revoked key will fail with 401 on their next call.


        Accepts either a session cookie or an existing API key as auth.'
      operationId: delete_api_key
      parameters:
      - name: id
        in: path
        description: API key ID (from the `id` field on create / list)
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: Key deleted (idempotent — succeeds even if already absent)
        '401':
          description: Missing or invalid session / key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - BearerAuth: []
    servers:
    - url: https://www.audioscrape.com
      description: Production
  /api/keys/{id}/rotate:
    post:
      tags:
      - API Keys
      summary: Rotate an API key
      description: 'Atomically replaces the key''s secret (GH#485): the key keeps its id, name, workspace pin and expiry; the old secret stops authenticating the moment this call returns; the new secret is in `key_value` — shown only in this response. Prefer this over delete-and-recreate: the key''s identity survives and there is no window with zero valid credentials. `last_used` resets to `null` because the new secret has never been used.


        Accepts either a session cookie or an existing API key as auth. A key can rotate itself.'
      operationId: rotate_api_key
      parameters:
      - name: id
        in: path
        description: API key ID (from the `id` field on create / list)
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Key rotated. `key_value` holds the NEW secret, shown in full here for the only time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          description: Missing or invalid session / key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '404':
          description: No key with this id belongs to you
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - BearerAuth: []
    servers:
    - url: https://www.audioscrape.com
      description: Production
  /api/keys/{id}/usage:
    get:
      tags:
      - API Keys
      summary: Get a key's recent usage
      description: 'Returns how many requests authenticated with this key over the trailing 30 days. Pair with `last_used` / `last_used_ip` from the list endpoint to audit a credential before revoking or rotating it.


        Accepts either a session cookie or an existing API key as auth.'
      operationId: api_key_usage
      parameters:
      - name: id
        in: path
        description: API key ID (from the `id` field on create / list)
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Usage over the trailing 30-day window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyUsage'
        '401':
          description: Missing or invalid session / key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '404':
          description: No key with this id belongs to you
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - BearerAuth: []
    servers:
    - url: https://www.audioscrape.com
      description: Production
components:
  schemas:
    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.
    ApiKey:
      type: object
      required:
      - id
      - key_name
      - key_prefix
      properties:
        created_at:
          type:
          - string
          - 'null'
          description: RFC 3339 UTC timestamp.
          example: '2026-05-16T08:30:00Z'
        expires_at:
          type:
          - string
          - 'null'
          description: 'When the key stops authenticating (RFC 3339). `null` = never expires,

            which is the case for every key issued before 2026-07-31.'
        id:
          type: integer
          format: int64
        key_name:
          type: string
          description: Human-readable label for the key (shown in the dashboard).
          example: acme-dev-connector-v1
        key_prefix:
          type: string
          description: 'Display-safe prefix of the key (first 12 characters + "..."). Always

            present. Use this to identify the key in logs and UIs.'
          example: sk_abc123def...
        key_value:
          type:
          - string
          - 'null'
          description: 'The full bearer token, format `sk_<base64(32 random bytes)>`.

            **Returned only in the response to `POST /api/keys`** — Audioscrape

            stores only a SHA-256 hash, so list / delete endpoints cannot

            recover the raw value. Save it client-side immediately on creation.'
          example: sk_abc123base64encodedrandombytes...
        last_used:
          type:
          - string
          - 'null'
          description: 'RFC 3339 UTC timestamp of the most recent request that used this key.

            `null` if the key has never been used.'
          example: '2026-05-16T08:30:00Z'
        last_used_ip:
          type:
          - string
          - 'null'
          description: 'Source IP of the request described by `last_used` (as seen by our

            edge). `null` if the key has never been used or the IP was

            unavailable. Use it to spot a leaked key being used from somewhere

            unexpected.'
          example: 203.0.113.7
        workspace_id:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Workspace this key is scoped to. `null` means the key follows the

            user''s `current_workspace_id` at request time (legacy behavior).'
          example: 42
    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.
    ApiKeyUsage:
      type: object
      required:
      - key_id
      - window_days
      - requests
      properties:
        key_id:
          type: integer
          format: int64
        requests:
          type: integer
          format: int64
          description: Requests that authenticated with this key inside the window.
          example: 1204
        window_days:
          type: integer
          format: int64
          description: Trailing window the count covers, in days.
          example: 30
    CreateApiKey:
      type: object
      required:
      - key_name
      properties:
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
          description: 'Optional: when this key stops working (RFC 3339). Omit for a key that

            never expires — the behaviour of every key issued before 2026-07-31.'
          example: '2027-01-01T00:00:00Z'
        key_name:
          type: string
          description: 'Human-readable label for the key. Stored verbatim; visible in the

            dashboard and in `last_used` audit logs. Recommended: identify the

            integration + environment, e.g. `"acme-dev-connector-v1"`.'
          example: acme-dev-connector-v1
        workspace_id:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Optional: scope this key to a single workspace. If omitted, the key

            uses the user''s current_workspace_id at each request (legacy

            behavior). To scope to a workspace, the caller must be a member

            of it.'
          example: 42
  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