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/...

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 unchanged

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?