Connecting your own software to freedam through the REST API means the library stops being a place people visit and becomes infrastructure your systems read from and write to. Your website can pull product imagery straight from the source of truth, your pipeline can upload renders as they finish, and a retouched image can update everywhere at once — because everything points at the same asset.

What it does

The API is versioned: every endpoint lives under /api/v1 on your instance, and paths are stable within v1. It covers the library end to end:

• Assets — list, fetch, update, and delete assets. Assets are addressed by their GAID (Global Asset ID), a stable public identifier.
• Collections — create and manage collections, add and remove assets.
• Uploads — create an upload batch, push files as multipart requests, and poll batch status until ingestion completes.
• Metadata — read field definitions, controlled vocabularies, and terms, so your own UI can offer valid values without hard-coding them.
• Shares — create, update, and revoke share links with passwords, expiry, and download permissions.
• Operations — kick off long-running work (bulk update, bulk delete, AI analysis, exports) as asynchronous operations with idempotency keys.
• Webhooks — register endpoints, inspect deliveries, rotate signing secrets.
• Video embeds — mint iframe embed codes for video assets.
• Consents and tokens — audit terms-of-use acceptance and manage API tokens programmatically.

A machine-readable OpenAPI 3.1 specification for the whole surface is served at /docs/api.json. It is the source of truth the official TypeScript SDK is generated from, and you can feed it to any standard generator to produce a client in your language of choice.

How it works

Authentication is token-based. You create a token in Settings → API Tokens, pick the abilities it should carry — scopes like assets:read, collections:write, or shares:manage — and send it as a bearer header:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://your-instance.example.com/api/v1/assets

Each endpoint demands a specific ability, and a token can never be granted scopes beyond what its creator is allowed to do. When a request is refused, the response tells you exactly which abilities were missing, so fixing a token is a lookup, not a guessing game.

List endpoints paginate with page and per_page and return a standard data + meta envelope. Every authenticated request is recorded in an audit trail — user, token, method, path, status, response time, and client IP — and each token shows its last-used timestamp and IP, so an unexpected caller is easy to spot and revoke.

Good to know

• Rate limits are per token: 60 requests per minute, with X-RateLimit-* headers on every response and a Retry-After header on 429 responses. Use operations for bulk work — one request regardless of how many assets it touches — and webhooks instead of polling.
• Tokens are shown once at creation; only a hash is stored. Revocation is instant, with no grace period.
• Image delivery is separate: cookieless image transformation URLs live outside /api/v1 and are covered in their own part of the API docs.
• Self-hosted instances expose the same API at the same paths — your integrations move with you.

The full endpoint catalogue, scope reference, and error contract live in the API documentation. If you are weighing a self-hosted deployment and want to talk it through, get in touch.