---
title: "upload an image"
method: POST
path: "/api/images"
tags: ["images"]
---

# upload an image

`POST /api/images`

## Request

- Base URL: `https://dev.to`
- URL: `https://dev.to/api/images`
- Auth: one of:
  - API key in header `api-key`
  - HTTP bearer

Upload an image and get back a URL hosted by this Forem.

### Using the URL:
- Embed it in an article's `body_markdown`, e.g. `![A description](URL)`.
- Set it as an article's cover image by passing it as `main_image` when creating or updating an article.

### Limits:
- One image per request, sent as `multipart/form-data` in the `image` field.
- Allowed types: jpg, jpeg, jpe, gif, png, ico, bmp, dng, webp. Max 25MB.
- Rate limited per user to a configurable number of uploads per configurable window (by default 10 per hour). Exceeding it returns `429` with a `Retry-After` header. Forem admins can change both values, or set the limit to 0 to disable this endpoint.

## Request body `multipart/form-data`

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

## Response `201`

created

- ImageUrl: An image hosted by this Forem, usable in body_markdown or as an article's main_image
  - `url` string, url, required

## Other responses

- `401`: unauthorized
- `422`: unprocessable
- `429`: too many requests

## Changes

- **2026-10-12** (v1) `7b762577c2a4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/forem/apis/forem-api-v1/changes/api/images/post.md)

---

[API](https://skmtc.dev/forem/apis/forem-api-v1.md) - [All operations](https://skmtc.dev/forem/apis/forem-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/forem/apis/forem-api-v1/revisions/36f1cf80cf48?raw)