The Notes API from Buttondown — 3 operation(s) covering internal notes attached to subscribers and team members.
openapi: 3.1.0
info:
title: Buttondown Notes 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: Notes
paths:
/notes:
post:
operationId: create_note_endpoint
summary: Create Note Endpoint
parameters: []
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Note'
links:
delete_note_endpoint:
operationId: delete_note_endpoint
parameters:
path.id: $response.body#/id
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorMessage'
'409':
description: Conflict
'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: Create a new note
tags:
- Notes
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NoteInput'
required: true
security:
- ApiKeyAuth: []
get:
operationId: list_notes
summary: List Notes
parameters:
- in: query
name: model_type
schema:
description: Filter notes by the type of object they are attached to.
title: Model Type
enum:
- automation
- comment
- conversation
- email
- external_feed
- invitation
- socialmention
- stripe_customer
- subscriber
- survey
- tag
- webmention
type: string
required: false
description: Filter notes by the type of object they are attached to.
- in: query
name: model_id
schema:
description: Filter notes by the UUID or TypeID of the object they are attached to.
title: Model Id
maxLength: 50
pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:bsky_ss_doc|bsky_ss_pub|permission|unsub_req|auth_tok|rec_code|webauthn|api_req|aut_att|ext_evt|segment|str_cus|str_sub|sub_imp|sub_tag|adslot|em_dom|em_imp|le_evt|str_pd|adsku|socmn|webmn|book|bulk|cnvs|form|hook|inbx|news|note|resp|rssi|snip|snpr|acc|att|aut|com|emr|exp|img|inv|mes|rss|smp|srv|sub|dr|em)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
type: string
required: false
description: Filter notes by the UUID or TypeID of the object they are attached to.
- in: query
name: expand
schema:
description: If provided, expand the given field.
items:
const: user
type: string
title: Expand
type: array
required: false
description: If provided, expand the given field.
- in: query
name: page
required: false
description: The page number of the paginated response.
schema:
type: integer
title: Page
description: The page number of the paginated response.
default: 1
example: 1
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NotePage'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'409':
description: Conflict
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorMessage'
'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 notes
tags:
- Notes
security:
- ApiKeyAuth: []
/notes/{id}:
delete:
operationId: delete_note_endpoint
summary: Delete Note Endpoint
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
responses:
'204':
description: No Content
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'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
'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: Delete a note
tags:
- Notes
security:
- ApiKeyAuth: []
components:
schemas:
AccessLevel:
enum:
- none
- read
- write
title: AccessLevel
type: string
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
InvitationStatus:
type: string
enum:
- pending
- accepted
- declined
- revoked
- owner
title: InvitationStatus
description: An enumeration.
Note:
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
body:
description: The text content of the note.
example: This subscriber upgraded to a paid plan.
minLength: 1
pattern: '[\s\S]*\S[\s\S]*'
title: Body
type: string
model_type:
description: The type of object this note is attached to (e.g., 'email', 'subscriber').
enum:
- automation
- comment
- conversation
- email
- external_feed
- invitation
- socialmention
- stripe_customer
- subscriber
- survey
- tag
- webmention
example: email
title: Model Type
type: string
model_id:
description: The UUID or TypeID of the object this note is attached to.
example: 13121cd6-0dfc-424c-bb12-988b0a32fcb3
maxLength: 50
pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:bsky_ss_doc|bsky_ss_pub|permission|unsub_req|auth_tok|rec_code|webauthn|api_req|aut_att|ext_evt|segment|str_cus|str_sub|sub_imp|sub_tag|adslot|em_dom|em_imp|le_evt|str_pd|adsku|socmn|webmn|book|bulk|cnvs|form|hook|inbx|news|note|resp|rssi|snip|snpr|acc|att|aut|com|emr|exp|img|inv|mes|rss|smp|srv|sub|dr|em)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
title: Model Id
type: string
metadata:
additionalProperties: true
title: Metadata
type: object
source:
description: The source of the note. If the note was created by a Buttondown admin, this will be 'admin'; otherwise,
it will be 'user'.
enum:
- admin
- user
example: admin
title: Source
type: string
user_id:
anyOf:
- type: string
- type: 'null'
title: User Id
user:
anyOf:
- $ref: '#/components/schemas/User'
- type: 'null'
required:
- id
- creation_date
- body
- model_type
- model_id
- metadata
- source
title: Note
type: object
NoteInput:
properties:
body:
description: The text content of the note.
example: This subscriber upgraded to a paid plan.
minLength: 1
pattern: '[\s\S]*\S[\s\S]*'
title: Body
type: string
model_type:
description: The type of object this note is attached to (e.g., 'email', 'subscriber').
enum:
- automation
- comment
- conversation
- email
- external_feed
- invitation
- socialmention
- stripe_customer
- subscriber
- survey
- tag
- webmention
example: email
title: Model Type
type: string
model_id:
description: The UUID or TypeID of the object this note is attached to.
example: 13121cd6-0dfc-424c-bb12-988b0a32fcb3
maxLength: 50
pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:bsky_ss_doc|bsky_ss_pub|permission|unsub_req|auth_tok|rec_code|webauthn|api_req|aut_att|ext_evt|segment|str_cus|str_sub|sub_imp|sub_tag|adslot|em_dom|em_imp|le_evt|str_pd|adsku|socmn|webmn|book|bulk|cnvs|form|hook|inbx|news|note|resp|rssi|snip|snpr|acc|att|aut|com|emr|exp|img|inv|mes|rss|smp|srv|sub|dr|em)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
title: Model Id
type: string
metadata:
additionalProperties: true
default: {}
description: A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be
nested — you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))
title: Metadata
type: object
required:
- body
- model_type
- model_id
title: NoteInput
type: object
NotePage:
properties:
results:
description: The list of results for this page.
items:
$ref: '#/components/schemas/Note'
title: Results
type: array
next:
anyOf:
- type: string
- type: 'null'
description: The URL to the next page of results, if any.
title: Next
previous:
anyOf:
- type: string
- type: 'null'
description: The URL to the previous page of results, if any.
title: Previous
count:
description: The total number of results across all pages.
title: Count
type: integer
required:
- results
- count
title: Page[Note]
type: object
Permissions:
properties:
subscriber:
allOf:
- $ref: '#/components/schemas/AccessLevel'
default: none
description: Access level for subscriber management.
email:
allOf:
- $ref: '#/components/schemas/AccessLevel'
default: none
description: Access level for email management.
sending:
allOf:
- $ref: '#/components/schemas/AccessLevel'
default: none
description: Access level for sending emails.
styling:
allOf:
- $ref: '#/components/schemas/AccessLevel'
default: none
description: Access level for newsletter styling.
administrivia:
allOf:
- $ref: '#/components/schemas/AccessLevel'
default: none
description: Access level for account administration.
automations:
allOf:
- $ref: '#/components/schemas/AccessLevel'
default: none
description: Access level for automation management.
surveys:
allOf:
- $ref: '#/components/schemas/AccessLevel'
default: none
description: Access level for survey management.
forms:
allOf:
- $ref: '#/components/schemas/AccessLevel'
default: none
description: Access level for form management.
title: Permissions
type: object
User:
properties:
permissions:
$ref: '#/components/schemas/Permissions'
email_address:
description: The email address of the user.
title: Email Address
type: string
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:
$ref: '#/components/schemas/InvitationStatus'
description: The status of the user's invitation (e.g. `pending`, `accepted`).
last_logged_in:
anyOf:
- format: date-time
type: string
- type: 'null'
description: When the user last logged in, or null if they haven't accepted the invitation.
title: Last Logged In
required:
- permissions
- email_address
- id
- creation_date
- status
title: User
type: object
ValidationErrorDetail:
properties:
type:
description: The type of validation error.
title: Type
type: string
loc:
description: The location of the error in the request.
items:
anyOf:
- type: string
- type: integer
title: Loc
type: array
msg:
description: A human-readable error message.
title: Msg
type: string
required:
- type
- loc
- msg
title: ValidationErrorDetail
type: object
ValidationErrorMessage:
properties:
detail:
description: A list of validation errors.
items:
$ref: '#/components/schemas/ValidationErrorDetail'
title: Detail
type: array
required:
- detail
title: ValidationErrorMessage
type: object
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: API key passed as 'Token <your-api-key>' in the Authorization header.