The API Requests API from Buttondown — 2 operation(s) covering the account's own API request log, including retained response bodies for idempotent requests.
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.