How to Automate Your Image and Video Uploads With Our API

Uploading files through a browser works fine when a human is sitting at the keyboard. It falls apart the moment you want a script, a bot, a build pipeline, or a backup job to do the uploading instead. That is exactly what the YourImageShare upload API is for: a small, free REST API that lets any program upload, list, and delete images and videos without ever touching a browser.

This guide walks through getting an API key, making your first upload, and a few real automation ideas worth building once the basics click.

Why automate uploads at all

A surprising number of workflows end up needing somewhere to put an image or a short video and get a link back. A monitoring script that screenshots a failing dashboard and posts the link to a chat channel. A build pipeline that uploads a test failure screenshot alongside a status report. A personal backup script that mirrors a folder of photos somewhere off your own machine. A Discord or Slack bot that needs to re-host a file a user sent it. None of these want a person clicking an upload button, they want a single HTTP request that returns a URL.

That is the entire job of the API documented at yourimageshare.com/about/api: three endpoints, a simple auth model, and JSON in and out.

Getting an API key

Every request needs a key. Sign in to your account at yourimageshare.com and open the API tab under My account. Your key is shown there along with a regenerate button, in case it ever leaks or you just want a fresh one. The key can be sent two ways: as a ?key= query parameter, or as an X-API-Key header. Both work identically, the header is generally the cleaner choice for scripts since it keeps the key out of logs that record full request URLs.

Your first upload

The upload endpoint is a single POST to /api, sent as multipart/form-data with the file in a field named uploads. From a terminal, that looks like this:

curl "https://yourimageshare.com/api?key=YOUR_API_KEY" -F "uploads=@/path/to/photo.jpg"

A successful upload returns a JSON object with the file's id, its type, the raw storage path, a direct file URL suitable for an image tag, and a direct link to the file's page on the platform. From there it is a matter of parsing that JSON in whatever language the automation is written in and doing something with the returned link, whether that is posting it to a chat webhook, saving it to a database, or embedding it in a generated report.

Listing and deleting programmatically

The API is not just a one-way upload pipe. GET /api lists your uploads, newest first, fifty per page, which is useful for a script that wants to check what has already been sent before uploading something new, or for building a small dashboard of everything a bot account has posted over time. DELETE /api/{id} removes a specific upload by its id, which matters for anything that generates a lot of short-lived files, like a CI pipeline that only needs a screenshot visible for as long as a pull request review is open.

Auto-deleting uploads

Not every automated upload needs to live forever. A one-time password screenshot, a temporary support attachment, or a CI artifact usually only matters for a few hours or days. Rather than writing a separate cleanup script to delete these later, the upload endpoint accepts an optional expires_in parameter, in seconds, from sixty seconds up to thirty days. Set it once at upload time and the file and its page disappear on their own once the window passes, with no extra API call required. This is documented in full, including exact timing behavior, on the API reference page.

Rate limits, and designing around them

Every API key gets twenty requests per minute and five hundred per day by default, with a two thousand per day ceiling per IP address as a backstop against abuse. Every response includes X-RateLimit-Limit and X-RateLimit-Remaining headers, so a well-behaved automation can check its remaining budget before firing off a burst of uploads rather than discovering it hit the ceiling from a 429 response. For anything uploading in bulk, like a script mirroring an entire photo library, spacing requests out with a short delay rather than firing them all at once keeps well inside these limits and avoids any risk of throttling mid-batch.

Official client libraries

Raw HTTP calls work fine, but if the automation is written in JavaScript or Python, official SDKs remove the boilerplate entirely. Both wrap the same three endpoints with typed results and raise a proper exception on API errors instead of leaving you to parse error JSON by hand. There is also an official MCP server for anyone building on top of AI agent tooling like Claude and ChatGPT, exposing upload, list, and delete as tools an agent can call directly — see how to use MCP with YourImageShare for a full walkthrough. All three are documented, with install commands and code samples, on the API documentation page.

A few real automation ideas

A status page monitor that captures a screenshot the moment a check fails and attaches the resulting link to an alert message, so whoever is on call sees exactly what broke without needing separate access to the monitoring tool. A personal script, run on a schedule, that walks a folder of exported photos and uploads anything new since the last run, keeping a lightweight off-site mirror without paying for a dedicated backup service. A support ticket bot that lets a customer paste a screenshot into a chat, uploads it automatically with a short expires_in window, and drops the resulting link into the ticket, so the image never needs to be stored permanently once the ticket closes. A build pipeline step that uploads a diff image or a failing test's rendered output as part of a status comment on a pull request, giving reviewers something concrete to look at instead of a wall of log text.

Handling errors gracefully

Every error response uses the same shape regardless of what went wrong, a JSON object with a type of error and a human-readable message. A 401 means the key is missing or wrong, worth checking for a stray typo or an accidentally regenerated key. A 422 covers validation failures, most commonly an unsupported file type or a file that failed the same automated moderation check every upload goes through, image or video, human or bot-driven. A 429 means the rate limit was hit, and the response includes a Retry-After header telling you exactly how long to wait before trying again. Building a small retry loop around that header, rather than guessing at a delay, keeps an automation resilient without needing to babysit it.

Choosing between raw HTTP and a client library

For a one-off script that runs once and is thrown away, a raw curl command or a handful of lines using your language's built in HTTP client is often the fastest path, and nothing here requires anything beyond standard multipart form handling. For anything longer lived, a scheduled job, a bot that runs continuously, a build pipeline step that will be maintained for years, the official JavaScript and Python libraries pay for themselves quickly. Error handling in particular gets tedious to write correctly by hand: checking the response status, parsing the error JSON, deciding whether a failure is worth retrying. The libraries handle all of that consistently, raising a typed exception with the real error message attached rather than leaving you to reconstruct what went wrong from a raw HTTP response. Both are documented, with install commands and working examples, on the API reference page.

Testing an integration safely before relying on it

Before wiring an automated upload into something that runs unattended, like a nightly backup job or a monitoring alert, it is worth testing the full flow manually first. Upload a throwaway file with curl using your real key, confirm the response looks the way your code expects, then delete it again with the delete endpoint so no test data lingers in your account. Doing this once before writing the automated version catches most integration mistakes early, things like a wrong field name on the file upload or a misread response field, rather than discovering them the first time the automation runs for real at three in the morning with nobody watching. The same manual check is worth repeating any time you change how an automation calls the API, even a small change, since a silent mismatch between what your code sends and what the API expects usually shows up as a confusing 422 rather than an obvious error.

Keeping an API key out of source control

A mistake worth avoiding early: never hardcode an API key directly into a script that gets committed to a repository, even a private one. Environment variables, a local config file excluded from version control, or a secrets manager if the automation runs somewhere with one available, all work fine and keep the key from ending up somewhere it can leak later. If a key does leak, or you simply want a clean rotation, regenerating it takes one click from the API tab in My account on yourimageshare.com, and the old key stops working immediately once a new one is generated.

Where automation fits next to manual uploads

None of this replaces the regular upload flow available on yourimageshare.com, it sits alongside it. Most accounts end up using both: the website for anything uploaded by hand, and the API for anything a script or bot handles on its own. Uploads made either way show up together in the same account, listed the same way, deletable the same way, so there is no split between an API account and a website account to keep track of.

Where to go from here

The full reference, covering every field in every response along with code samples in curl, JavaScript, Python, PHP, and Go, lives at yourimageshare.com/about/api. Getting an API key takes under a minute from the YourImageShare homepage, and the free tier is generous enough that most personal automations, bots, and small pipelines never need to think about upgrading.

If the automation ends up being a screenshot tool, a forum, or a chat bot rather than a custom script, there are also ready-made integrations, from ShareX and Flameshot configs to forum plugins for phpBB, SMF, and MyBB, that skip the coding step entirely and just need an API key pasted into a config file. Those are covered in more detail in a couple of companion posts on this blog, worth a look before writing a custom integration from scratch.

Whatever gets built, the same guarantee applies as the manual upload flow on yourimageshare.com: no account required to use the platform itself, files served fast from a global CDN, and a straightforward, documented API behind it rather than an undocumented one that might change without notice.

Building this into a forum instead of a standalone script? See adding a real upload button to phpBB, SMF, or MyBB.