Buttondown logo

Creating an image

Supported formats

Buttondown accepts PNG, JPG, GIF, and WebP images. Other formats are rejected by default because email clients and social preview crawlers do not render them reliably.

If you upload an unsupported image, the API will return a 422 with:

{
  "detail": [
    {
      "type": "value_error.file_extension",
      "loc": ["file", "image"],
      "msg": "Unsupported image type. Please upload a PNG, JPG, GIF, or WebP image."
    }
  ]
}

Bypassing format validation

If you know what you're doing (e.g. your file is only used on the web archive, not in emails or link previews), you can bypass this restriction by providing a X-Buttondown-Live-Dangerously header with a value of true:

curl -X POST "https://api.buttondown.com/v1/images" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "X-Buttondown-Live-Dangerously: true" \
  -F "image=@logo.svg"

Sample requests

These sample requests are autogenerated by the OpenAPI spec.

import requests

url = "https://api.buttondown.com/v1/images"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}
files = {
    "image": open("path/to/your/image.jpg", "rb")
}

response = requests.request("POST", url, headers=headers, files=files)
print(response.text)

Sample responses

The IDs and values referenced in these responses are fake; please only rely on these responses for overall structure.

{
    "creation_date": "2019-08-24T14:15:22Z",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "image": "https://placecats.com/408/287"
}

Body parameters

All parameters are optional unless explicitly specified.