The Snippets API from Buttondown — 5 operation(s) covering reusable content snippets referenced from emails.
openapi: 3.1.0
info:
title: Buttondown Snippets 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: Snippets
paths:
/snippets:
post:
operationId: create_snippet
summary: Create Snippet
parameters: []
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Snippet'
examples:
create_snippet:
summary: Create a snippet
value:
id: '{{ id }}'
creation_date: '2020-01-01T00:00:00Z'
identifier: footer
name: Footer
content: Thanks for reading!
mode: fancy
reference_count: 0
links:
retrieve_snippet:
operationId: retrieve_snippet
parameters:
path.id: $response.body#/id
update_snippet:
operationId: update_snippet
parameters:
path.id: $response.body#/id
delete_snippet:
operationId: delete_snippet
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'
'409':
description: Conflict
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorMessage'
'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: Create a new snippet
tags:
- Snippets
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SnippetInput'
examples:
create_snippet:
summary: Create a snippet
value:
identifier: footer
name: Footer
content: Thanks for reading!
required: true
security:
- ApiKeyAuth: []
get:
operationId: list_snippets
summary: List Snippets
parameters:
- in: query
name: page
schema:
description: The page number of the paginated response.
example:
- 1
title: Page
minimum: 1
type: integer
required: false
description: The page number of the paginated response.
example:
- 1
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SnippetPage'
examples:
list_snippets:
summary: List snippets
value:
results:
- id: '{{ id }}'
creation_date: '2020-01-01T00:00:00Z'
identifier: footer
name: Footer
content: Thanks for reading!
mode: fancy
reference_count: 0
next: null
previous: null
count: 1
'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'
'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 snippets
tags:
- Snippets
security:
- ApiKeyAuth: []
/snippets/{id}:
get:
operationId: retrieve_snippet
summary: Retrieve Snippet
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Snippet'
examples:
retrieve_snippet:
summary: Retrieve a snippet
value:
id: '{{ id }}'
creation_date: '2020-01-01T00:00:00Z'
identifier: footer
name: Footer
content: Thanks for reading!
mode: fancy
reference_count: 0
links:
update_snippet:
operationId: update_snippet
parameters:
path.id: $response.body#/id
delete_snippet:
operationId: delete_snippet
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'
'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 single snippet.
tags:
- Snippets
security:
- ApiKeyAuth: []
patch:
operationId: update_snippet
summary: Update Snippet
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Snippet'
examples:
update_snippet:
summary: Update a snippet's content
value:
id: '{{ id }}'
creation_date: '2020-01-01T00:00:00Z'
identifier: footer
name: Footer
content: Thanks for reading — reply any time!
mode: fancy
reference_count: 0
update_snippet_identifier:
summary: Rename a snippet's identifier
value:
id: '{{ id }}'
creation_date: '2020-01-01T00:00:00Z'
identifier: email-footer
name: Footer
content: Thanks for reading — reply any time!
mode: fancy
reference_count: 0
links:
retrieve_snippet:
operationId: retrieve_snippet
parameters:
path.id: $response.body#/id
delete_snippet:
operationId: delete_snippet
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'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'409':
description: Conflict
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorMessage'
'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: Update a snippet.
tags:
- Snippets
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SnippetUpdateInput'
examples:
update_snippet:
summary: Update a snippet's content
value:
name: Footer
content: Thanks for reading — reply any time!
update_snippet_identifier:
summary: Rename a snippet's identifier
value:
identifier: email-footer
required: true
security:
- ApiKeyAuth: []
delete:
operationId: delete_snippet
summary: Delete Snippet
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
responses:
'204':
description: No Content
'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: Delete a snippet.
tags:
- Snippets
security:
- ApiKeyAuth: []
components:
schemas:
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
Snippet:
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
identifier:
description: A unique, newsletter-scoped slug used to reference the snippet inside email content (e.g. `{{ snippets.footer
}}`). Must be unique per newsletter.
title: Identifier
type: string
name:
description: A human-readable name for the snippet, shown in the Buttondown UI.
title: Name
type: string
content:
description: The body of the snippet, substituted wherever the snippet is referenced. Interpreted according to `mode`.
title: Content
type: string
mode:
$ref: '#/components/schemas/SnippetMode'
description: 'The editor mode for the snippet, which controls how `content` is rendered: `fancy` (rich text, stored
as HTML), `plaintext` (Markdown), or `naked` (raw HTML with no processing).'
reference_count:
default: 0
description: The number of emails that currently reference this snippet.
title: Reference Count
type: integer
required:
- id
- creation_date
- identifier
- name
- content
- mode
title: Snippet
type: object
SnippetInput:
additionalProperties: false
properties:
identifier:
description: A unique, newsletter-scoped slug used to reference the snippet inside email content (e.g. `{{ snippets.footer
}}`). Must be unique per newsletter.
maxLength: 100
minLength: 1
pattern: ^[a-zA-Z0-9_-]+$
title: Identifier
type: string
example: footer
name:
description: A human-readable name for the snippet, shown in the Buttondown UI.
maxLength: 255
minLength: 1
title: Name
type: string
example: Footer
content:
default: ''
description: The body of the snippet, substituted wherever the snippet is referenced. Interpreted according to `mode`.
title: Content
type: string
example: Thanks for reading!
mode:
allOf:
- $ref: '#/components/schemas/SnippetMode'
default: fancy
description: 'The editor mode for the snippet, which controls how `content` is rendered: `fancy` (rich text, stored
as HTML), `plaintext` (Markdown), or `naked` (raw HTML with no processing).'
example: fancy
required:
- identifier
- name
title: SnippetInput
type: object
SnippetMode:
enum:
- fancy
- naked
- plaintext
title: Mode
type: string
description: An enumeration.
SnippetPage:
properties:
results:
description: The list of results for this page.
items:
$ref: '#/components/schemas/Snippet'
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[Snippet]
type: object
SnippetUpdateInput:
additionalProperties: false
properties:
identifier:
anyOf:
- maxLength: 100
minLength: 1
pattern: ^[a-zA-Z0-9_-]+$
type: string
- type: 'null'
description: A unique, newsletter-scoped slug used to reference the snippet inside email content (e.g. `{{ snippets.footer
}}`). Must be unique per newsletter.
title: Identifier
example: footer
name:
anyOf:
- maxLength: 255
minLength: 1
type: string
- type: 'null'
description: A human-readable name for the snippet, shown in the Buttondown UI.
title: Name
example: Footer
content:
anyOf:
- type: string
- type: 'null'
description: The body of the snippet, substituted wherever the snippet is referenced. Interpreted according to `mode`.
title: Content
example: Thanks for reading!
mode:
anyOf:
- $ref: '#/components/schemas/SnippetMode'
- type: 'null'
description: 'The editor mode for the snippet, which controls how `content` is rendered: `fancy` (rich text, stored
as HTML), `plaintext` (Markdown), or `naked` (raw HTML with no processing).'
example: fancy
title: SnippetUpdateInput
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.