Ferndesk
All Collections

Image Uploads

When you create or update an article through the public API, you can include images in the article body using external URLs or base64 data URLs. The API uploads them to Ferndesk and stores them as asset paths.

Endpoints

Image uploading is handled automatically when you write article content through these endpoints:

  • POST /articles

  • PATCH /articles/:id

Accepted image sources

You can use these formats in the src field of image nodes inside the article body:

  • External URLs — absolute URLs pointing to images hosted elsewhere

  • Base64 data URLs — data:image/...;base64,... strings

  • Ferndesk asset urls — images already hosted by Ferndesk via https://static.ferndesk.com/user-images/...

External image URL requirements

External URLs must point to a publicly reachable image over HTTP or HTTPS. URLs that fail these requirements are rejected during the write request.

  • Only http and https URLs are accepted.

  • The URL must resolve to a publicly reachable address. Addresses that are not publicly reachable are rejected, including when a redirect leads to one.

  • Redirects are validated at every hop, up to a maximum of five.

  • Downloads are limited to 50 MiB and must finish within 45 seconds. SVG images are limited to 2 MiB.

  • Responses served as HTML, XML, JavaScript, executable, or similar unsafe types are rejected, even when the filename looks like an image. SVGs are sanitized before storage.

When an external URL fails one of these requirements, the API returns the upload failure response described under Error responses.

What happens

When you send a write request, the API:

  • Uploads external URLs and base64 data URLs to Ferndesk servers

  • Replaces the original src values in the stored article with the new Ferndesk paths

  • Leaves existing Ferndesk-hosted images in place without re-uploading; static Ferndesk URLs are normalized to asset paths

If the same image source appears multiple times in one request, it is uploaded once and all references share the same path.

There is no standalone public API endpoint for uploading images. Include images directly in the article body when you call POST /articles or PATCH /articles/:id, and the upload happens during the write.

Error responses

If an image cannot be processed, the API returns an explicit error and the article is not saved.

Malformed base64

400 with:

{
  "error": "Image data URL must contain valid base64 data",
  "code": "invalid_request"
}

Upload failure

502 with:

{
  "error": "Unable to upload one or more article images",
  "code": "image_upload_failed"
}

Was this helpful?
Was this helpful?