---
title: "Upload an image"
method: POST
path: "/images"
tags: ["Images"]
---

# Upload an image

`POST /images`

## Request

- Base URL: `https://enterprise.knak.io/api/published/v1`
- URL: `https://enterprise.knak.io/api/published/v1/images`
- Auth: none declared
- TypeScript: <https://skmtc.dev/knak/apis/knak-enterprise-api/docs/images/post.ts> (a function with typed inputs; its response is checked against the schema)

Upload a single image to your company's image library and get back a permanent public URL you can use in emails. Images are stored in an "API Uploads" folder at the root of the image library, visible to every brand.

Accepted formats are PNG, JPEG, WebP, HEIC and HEIF, up to 5MB and 4096 pixels on the longest side.

Uploading a file identical to one your company uploaded through the API in the last 30 days returns the existing image with a 200 instead of storing a copy, so retrying a failed or timed-out upload is safe. A new image returns a 201.

Uploads are limited to 30 requests per minute per user and 1,000 per day per company. Every request counts toward both limits, including re-uploads of an existing image and requests that fail validation.

## Request body `multipart/form-data`

- object
  - `image` string, binary, required: The image file to upload.

## Response `200`

An identical image was uploaded in the last 30 days; the existing image is returned.

- Image
  - `data` object
    - `type` string
    - `id` string: ID of the image in the company's image library.
    - `attributes` object
      - `name` string: File name in the image library. Taken from the uploaded file and made unique within the folder.
      - `url` string: Permanent public URL of the image, ready to use in an email.

## Other responses

- `201`: The image was stored.
- `400`: Bad Request - the file is missing, not an accepted image type, larger than 5MB, or larger than 4096 pixels on a side.
- `401`: Unauthenticated
- `403`: Forbidden
- `429`: Too Many Requests - more than 30 requests in a minute by this user, or more than 1,000 in a day by this company. Retry no sooner than the `Retry-After` header indicates.
- `default`: Unexpected server error.

---

[API](https://skmtc.dev/knak/apis/knak-enterprise-api.md) - [All operations](https://skmtc.dev/knak/apis/knak-enterprise-api/llms.txt) - [OpenAPI document](https://skmtc.dev/knak/apis/knak-enterprise-api/revisions/31d2c94edfcc?raw)