REST API
The REST API turns your freedam library from a place people visit into something your other systems can plug into. Your website can pull product imagery straight from the source of truth, your production tools can drop finished files in automatically, and when an image gets retouched, it updates everywhere at once - because everything points at the same asset.
What it does
The API covers the whole library, and its addresses stay stable so integrations you build today keep working:
- Assets - list, fetch, update, and delete assets. Each asset has a permanent public ID, so links to it never break.
- Collections - create and manage collections, add and remove assets.
- Uploads - send files in batches and check on their progress until they are fully processed.
- Metadata - read your field definitions and approved vocabulary terms, so your own tools can offer valid values without hard-coding them.
- Shares - create, update, and revoke share links, including passwords, expiry dates, and download permissions.
- Operations - start big jobs (bulk updates, bulk deletes, AI analysis, exports) and let them run in the background.
- Webhooks - have freedam notify your systems when something happens, instead of your systems asking over and over.
- Video embeds - generate embed codes for video assets.
- Consents and tokens - review terms-of-use acceptance and manage API access programmatically.
The API also publishes a machine-readable description of itself (an OpenAPI specification). That is what the official TypeScript SDK is built from, and developers can use it to generate a ready-made client in almost any programming language.
How it works
Access is controlled with tokens. You create one in Settings → API Tokens and choose exactly what it is allowed to do - for example, read assets but never delete them. Whatever software holds that token can do those things and nothing more:
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://your-instance.example.com/api/v1/assets
A token can never be granted more power than the person who created it has. And when a request is refused, the response says exactly which permission was missing, so fixing it is a lookup, not a guessing game.
Every API request is also recorded in an audit trail - who called, with which token, doing what, and from where. Each token shows when and from where it was last used, so an unexpected caller is easy to spot and revoke.
Good to know
- There are sensible speed limits: each token can make 60 requests per minute, and responses tell callers when to slow down. For big jobs, use operations - one request no matter how many assets it touches - and webhooks instead of repeated checking.
- Tokens are shown once when created; freedam never stores the token itself. Revoking one takes effect instantly.
- Image delivery is separate: fast, cookie-free image URLs for your website have their own section in the API docs.
- Self-hosted instances have the same API at the same addresses - your integrations move with you.
The full endpoint catalogue and reference material live in the API documentation. If you are weighing a self-hosted deployment and want to talk it through, get in touch.