The Users API from Buttondown — 5 operation(s) covering team members on the account and their permissions.
openapi: 3.1.0
info:
title: Buttondown Users 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: Users
paths:
/users:
post:
operationId: create_user
summary: Create User
parameters: []
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
links:
retrieve_user:
operationId: retrieve_user
parameters:
path.id: $response.body#/id
update_user:
operationId: update_user
parameters:
path.id: $response.body#/id
delete_user:
operationId: delete_user
parameters:
path.id: $response.body#/id
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage_Failure_'
'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: Invite a new user to the newsletter
tags:
- Users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserInput'
required: true
security:
- ApiKeyAuth: []
get:
operationId: list_users
summary: List Users
parameters:
- 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/UserPage'
'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 users
tags:
- Users
security:
- ApiKeyAuth: []
/users/{id}:
get:
operationId: retrieve_user
summary: Retrieve User
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
links:
update_user:
operationId: update_user
parameters:
path.id: $response.body#/id
delete_user:
operationId: delete_user
parameters:
path.id: $response.body#/id
'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 user by its ID
tags:
- Users
security:
- ApiKeyAuth: []
delete:
operationId: delete_user
summary: Delete User
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 user
tags:
- Users
security:
- ApiKeyAuth: []
patch:
operationId: update_user
summary: Update User
parameters:
- in: path
name: id
schema:
title: Id
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
links:
retrieve_user:
operationId: retrieve_user
parameters:
path.id: $response.body#/id
delete_user:
operationId: delete_user
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: Update a user's properties
tags:
- Users
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserUpdateInput'
required: true
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
ErrorMessage_Failure_:
properties:
code:
allOf:
- $ref: '#/components/schemas/Failure'
description: The error code.
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[Failure]
type: object
Failure:
enum:
- email_already_exists
title: Failure
type: string
description: An enumeration.
InvitationStatus:
type: string
enum:
- pending
- accepted
- declined
- revoked
- owner
title: InvitationStatus
description: An enumeration.
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
UserInput:
properties:
permissions:
$ref: '#/components/schemas/Permissions'
email_address:
description: The email address of the user.
title: Email Address
type: string
required:
- permissions
- email_address
title: UserInput
type: object
UserPage:
properties:
results:
description: The list of results for this page.
items:
$ref: '#/components/schemas/User'
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[User]
type: object
UserUpdateInput:
properties:
permissions:
$ref: '#/components/schemas/Permissions'
required:
- permissions
title: UserUpdateInput
type: object
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: API key passed as 'Token <your-api-key>' in the Authorization header.