openapi: 3.1.0
info:
  title: Buttondown API Requests API
  version: 1.0.0
  description: The Buttondown API lets you manage newsletters, subscribers, emails, and more. See [the documentation](https://docs.buttondown.com/api-introduction)
    for guides and examples.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.buttondown.com/v1
security:
- ApiKeyAuth: []
tags:
- name: API Requests
paths:
  /api_requests/{id}:
    get:
      operationId: retrieve_api_request
      summary: Retrieve Api Request
      parameters:
      - in: path
        name: id
        schema:
          title: Id
          type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRequestDetail'
          links: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Requests permitted per minute.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: Retrieve a specific API request by its ID
      tags:
      - API Requests
      security:
      - ApiKeyAuth: []
  /api_requests:
    get:
      operationId: list_api_requests
      summary: List Api Requests
      parameters:
      - in: query
        name: api_key_id
        schema:
          default: []
          description: If provided, only return requests made with the given [API key](https://docs.buttondown.com/api-authentication)
            ID(s).
          items:
            type: string
          title: Api Key Id
          type: array
        required: false
        description: If provided, only return requests made with the given [API key](https://docs.buttondown.com/api-authentication)
          ID(s).
      - in: query
        name: creation_date__gt
        schema:
          description: If provided, only return requests created after the given datetime.
          example: '2024-01-01T00:00:00Z'
          title: Creation Date  Gt
          format: date-time
          type: string
        required: false
        description: If provided, only return requests created after the given datetime.
        example: '2024-01-01T00:00:00Z'
      - in: query
        name: creation_date__lt
        schema:
          description: If provided, only return requests created before the given datetime.
          example: '2024-12-31T23:59:59Z'
          title: Creation Date  Lt
          format: date-time
          type: string
        required: false
        description: If provided, only return requests created before the given datetime.
        example: '2024-12-31T23:59:59Z'
      - in: query
        name: date__end
        schema:
          description: If provided, only return requests created on or before the given date.
          title: Date  End
          format: date
          type: string
        required: false
        description: If provided, only return requests created on or before the given date.
      - in: query
        name: date__start
        schema:
          description: If provided, only return requests created on or after the given date.
          title: Date  Start
          format: date
          type: string
        required: false
        description: If provided, only return requests created on or after the given date.
      - in: query
        name: limit
        schema:
          description: The maximum number of results to return per page.
          example: 100
          title: Limit
          type: integer
        required: false
        description: The maximum number of results to return per page.
        example: 100
      - in: query
        name: method
        schema:
          description: If provided, only return requests with the given HTTP method(s).
          example:
          - GET
          - POST
          items:
            type: string
          title: Method
          type: array
        required: false
        description: If provided, only return requests with the given HTTP method(s).
        example:
        - GET
        - POST
      - in: query
        name: path
        schema:
          default: []
          description: If provided, only return requests matching the given API path(s).
          items:
            type: string
          title: Path
          type: array
        required: false
        description: If provided, only return requests matching the given API path(s).
      - in: query
        name: source
        schema:
          description: If provided, only return requests from the given source(s).
          example:
          - api
          items:
            $ref: '#/components/schemas/APIRequestSource'
          title: Source
          type: array
        required: false
        description: If provided, only return requests from the given source(s).
        example:
        - api
      - in: query
        name: status_code
        schema:
          description: If provided, only return requests with the given HTTP status code(s).
          example:
          - '200'
          - '404'
          items:
            type: string
          title: Status Code
          type: array
        required: false
        description: If provided, only return requests with the given HTTP status code(s).
        example:
        - '200'
        - '404'
      - in: query
        name: version
        schema:
          description: If provided, only return requests made with the given [API version](https://docs.buttondown.com/api-versioning)(s).
          title: Version
          items:
            enum:
            - '2024-07-01'
            - '2024-08-01'
            - '2024-08-15'
            - '2024-09-30'
            - '2024-12-30'
            - '2025-01-02'
            - '2025-05-19'
            - '2025-06-01'
            - '2026-01-01'
            - '2026-04-01'
            type: string
          type: array
        required: false
        description: If provided, only return requests made with the given [API version](https://docs.buttondown.com/api-versioning)(s).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRequestList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Requests permitted per minute.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: List all API requests
      tags:
      - API Requests
      security:
      - ApiKeyAuth: []
components:
  schemas:
    APIRequest:
      description: Represents a request to the API (api.buttondown.com).
      properties:
        id:
          description: A unique TypeID associated with the object.
          title: Id
          type: string
        creation_date:
          description: The date and time at which the object was first created.
          format: date-time
          title: Creation Date
          type: string
        status_code:
          description: The HTTP status code the API returned.
          title: Status Code
          type: integer
        path:
          description: The request path (e.g. `/v1/subscribers`).
          title: Path
          type: string
        method:
          description: The HTTP method used (e.g. `GET`, `POST`).
          title: Method
          type: string
        source:
          $ref: '#/components/schemas/APIRequestSource'
          description: Where the request originated (e.g. `api`, `dashboard`).
        version:
          description: The API version the request was made against.
          enum:
          - '2024-07-01'
          - '2024-08-01'
          - '2024-08-15'
          - '2024-09-30'
          - '2024-12-30'
          - '2025-01-02'
          - '2025-05-19'
          - '2025-06-01'
          - '2026-01-01'
          - '2026-04-01'
          title: Version
          type: string
        ip_address:
          description: The IP address the request was made from.
          title: Ip Address
          type: string
        api_key_id:
          anyOf:
          - type: string
          - type: 'null'
          description: The ID of the API key used, if authenticated via API key.
          title: Api Key Id
        api_key_label:
          anyOf:
          - type: string
          - type: 'null'
          description: The human-readable label of the API key used, if any.
          title: Api Key Label
      required:
      - id
      - creation_date
      - status_code
      - path
      - method
      - source
      - version
      - ip_address
      title: APIRequest
      type: object
    APIRequestDetail:
      description: Represents a request to the API (api.buttondown.com).
      properties:
        id:
          description: A unique TypeID associated with the object.
          title: Id
          type: string
        creation_date:
          description: The date and time at which the object was first created.
          format: date-time
          title: Creation Date
          type: string
        status_code:
          description: The HTTP status code the API returned.
          title: Status Code
          type: integer
        path:
          description: The request path (e.g. `/v1/subscribers`).
          title: Path
          type: string
        method:
          description: The HTTP method used (e.g. `GET`, `POST`).
          title: Method
          type: string
        source:
          $ref: '#/components/schemas/APIRequestSource'
          description: Where the request originated (e.g. `api`, `dashboard`).
        version:
          description: The API version the request was made against.
          enum:
          - '2024-07-01'
          - '2024-08-01'
          - '2024-08-15'
          - '2024-09-30'
          - '2024-12-30'
          - '2025-01-02'
          - '2025-05-19'
          - '2025-06-01'
          - '2026-01-01'
          - '2026-04-01'
          title: Version
          type: string
        ip_address:
          description: The IP address the request was made from.
          title: Ip Address
          type: string
        api_key_id:
          anyOf:
          - type: string
          - type: 'null'
          description: The ID of the API key used, if authenticated via API key.
          title: Api Key Id
        api_key_label:
          anyOf:
          - type: string
          - type: 'null'
          description: The human-readable label of the API key used, if any.
          title: Api Key Label
        request_data:
          description: The raw request body, JSON-encoded as a string.
          title: Request Data
          type: string
        response_data:
          anyOf:
          - type: string
          - type: 'null'
          description: The raw response body, JSON-encoded as a string, if retained.
          title: Response Data
        headers:
          additionalProperties:
            type: string
          description: The request headers. UUIDs within header values are redacted.
          title: Headers
          type: object
      required:
      - id
      - creation_date
      - status_code
      - path
      - method
      - source
      - version
      - ip_address
      - request_data
      - headers
      title: APIRequestDetail
      type: object
    APIRequestList:
      properties:
        results:
          description: The list of API requests on this page.
          items:
            $ref: '#/components/schemas/APIRequest'
          title: Results
          type: array
        cursor:
          anyOf:
          - type: string
          - type: 'null'
          description: An opaque cursor to pass back to fetch the next page, or null if this is the last page.
          title: Cursor
      required:
      - results
      title: APIRequestList
      type: object
    APIRequestSource:
      type: string
      enum:
      - api
      - app
      - axios
      - carrd
      - cli
      - curl
      - go
      - make
      - netlify
      - node
      - pipedream
      - powershell
      - python
      - ruby
      - wordpress
      - zapier
      title: APIRequestSource
      description: An enumeration.
    ErrorMessage:
      properties:
        code:
          description: The error code.
          title: Code
          type: string
        detail:
          description: A human-readable description of the error.
          title: Detail
          type: string
        metadata:
          additionalProperties:
            type: string
          default: {}
          description: Additional context about the error. When present, a `documentation_url` key links to docs explaining
            how to resolve it.
          title: Metadata
          type: object
      required:
      - detail
      title: ErrorMessage
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key passed as 'Token <your-api-key>' in the Authorization header.