API Endpoints

All v1 endpoints are mounted under https://your-freedam-instance.com/api/v1 and require a Sanctum bearer token. Every request is rate limited (60/minute per token) and audited.

For authentication and token scopes see API Authentication. For rate-limit headers and the back-off contract see Rate Limiting. For the cookieless image transformation URLs (/i/, /is/, /ip/) and other asset delivery URLs that live outside /api/v1, see Image Transformations.

Conventions

• Base URL — https://your-freedam-instance.com/api/v1
• Auth header — Authorization: Bearer <your-token>
• JSON body — send Content-Type: application/json on POST/PUT
• Pagination — list endpoints accept page and per_page (default 20). Responses follow Laravel's standard data + meta envelope.
• Asset identifier — assets are addressed by their GAID (Global Asset ID), a stable, non-numeric public id.
• Numeric routes — {collection}, {webhook}, {batch} are constrained to numeric ids; other routes accept the resource's natural identifier.

Endpoint catalogue

User

Method	Path	Description
GET	/v1/user	Authenticated user (id, name, email).

Tokens

Self-service token management — see Authentication.

Method	Path	Description
GET	/v1/tokens	List the caller's tokens.
POST	/v1/tokens	Create a new token. Plain text returned once.
DELETE	/v1/tokens/{token}	Revoke a token immediately.

Assets

Required abilities: assets:read, assets:write, assets:delete, assets:download. Assets are addressed by their GAID (Global Asset ID).

Method	Path	Ability
GET	/v1/assets	assets:read
GET	/v1/assets/{gaid}	assets:read
PUT	/v1/assets/{gaid}	assets:write
DELETE	/v1/assets/{gaid}	assets:delete

Video Embeds

Generate iframe embed codes for video assets. Each call mints (or reuses) a long-lived public share dedicated to embedding so you can drop the returned iframe_html straight into a CMS, blog post, or third-party site. Embed shares are isolated from regular /v1/shares and cannot be reached through that endpoint.

Required abilities: shares:read for GET, shares:manage for POST and DELETE.

Method	Path	Ability	Description
GET	/v1/assets/{gaid}/embed	shares:read	Return the existing embed code, or 404 if none.
POST	/v1/assets/{gaid}/embed	shares:manage	Generate or refresh an embed code.
DELETE	/v1/assets/{gaid}/embed	shares:manage	Revoke the embed code.

Only assets with a video/* MIME type can be embedded; calling these endpoints on any other asset returns 422.

Request body for POST (all fields optional)

Field	Type	Default	Notes
width	integer	640	Player width in pixels for the non-responsive iframe (160–3840).
height	integer	360	Player height in pixels (90–2160).
responsive	boolean	true	If true, the response also includes a responsive_html snippet.
autoplay	boolean	false	Browsers force muted when autoplay is on.
muted	boolean	false	Start muted.
loop	boolean	false	Restart playback on end.
controls	boolean	true	Show the player chrome.
start	integer	0	Start offset in seconds.
allowed_domains	array of string	null	Restrict the iframe to these origins via CSP frame-ancestors.
force_new	boolean	false	Revoke the existing embed share and mint a fresh one.

Response

{
    "data": {
        "token": "shr_…",
        "asset_gaid": "A_01HXYZ…",
        "embed_url": "https://your-freedam-instance.com/embed/shr_…/A_01HXYZ…?autoplay=1",
        "iframe_html": "<iframe src=\"…\" width=\"640\" height=\"360\" …></iframe>",
        "responsive_html": "<div style=\"position:relative;padding-bottom:56.25%…\">…</div>",
        "width": 640,
        "height": 360,
        "expires_at": "2027-05-06T12:00:00+00:00",
        "allowed_domains": null,
        "options": {
            "autoplay": false,
            "muted": false,
            "loop": false,
            "controls": true,
            "start": 0
        }
    }
}

A repeated POST for the same asset returns 200 with the existing share (and refreshes its expiry when it is within 30 days of expiring); a fresh share returns 201.

Collections

Required abilities: collections:read, collections:write, collections:delete. The add/remove actions accept { "asset_ids": ["gaid_..."] }.

Method	Path	Ability
GET	/v1/collections	collections:read
GET	/v1/collections/{collection}	collections:read
POST	/v1/collections	collections:write
PUT	/v1/collections/{collection}	collections:write
DELETE	/v1/collections/{collection}	collections:delete
POST	/v1/collections/{collection}/assets	collections:write
DELETE	/v1/collections/{collection}/assets	collections:write

Uploads

Ability: uploads:manage. Files are uploaded as multipart/form-data to POST /v1/uploads/batches/{batch}/files. Track ingestion progress with GET /v1/uploads/batches/{batch} until status === "completed".

Method	Path	Description
POST	/v1/uploads/batches	Create an upload batch.
POST	/v1/uploads/batches/{batch}/files	Upload one file into the batch (multipart).
GET	/v1/uploads/batches/{batch}	Read batch status and per-file progress.

Metadata

Ability: metadata:read. Read-only catalog of field definitions, vocabularies, and terms. Use this to populate dropdowns in your own UI without hard-coding tenant-specific values.

Method	Path
GET	/v1/metadata/definitions
GET	/v1/metadata/vocabularies
GET	/v1/metadata/vocabularies/{vocabulary}
GET	/v1/metadata/vocabularies/{vocabulary}/terms
GET	/v1/metadata/vocabularies/{vocabulary}/terms/{term}

Shares

Abilities: shares:read, shares:manage. A share generates a public URL with optional password, expiry, allowed-emails/domains, and download permissions. revoke permanently deactivates a share.

Method	Path	Ability
GET	/v1/shares	shares:read
GET	/v1/shares/{share}	shares:read
POST	/v1/shares	shares:manage
PUT	/v1/shares/{share}	shares:manage
DELETE	/v1/shares/{share}	shares:manage
POST	/v1/shares/{share}/revoke	shares:manage

Operations

Long-running asynchronous operations (bulk update, bulk delete, AI analysis, exports). POST /v1/operations requires an Idempotency-Key header — replaying the same key returns the original operation instead of creating a new one. Supported type values: asset_upload_batch, asset_bulk_update, asset_bulk_delete, ai_analyze, export_download.

Method	Path
GET	/v1/operations
POST	/v1/operations
GET	/v1/operations/{operation}
POST	/v1/operations/{operation}/cancel

Webhooks

See Webhooks.

Method	Path
GET	/v1/webhooks
POST	/v1/webhooks
GET	/v1/webhooks/{webhook}
PUT	/v1/webhooks/{webhook}
DELETE	/v1/webhooks/{webhook}
POST	/v1/webhooks/{webhook}/test
GET	/v1/webhooks/{webhook}/deliveries
POST	/v1/webhooks/{webhook}/rotate-secret

Consents

Compliance and audit endpoints. Ability: consents:read. Returns terms-of-use acceptance status and the append-only history (paginated).

Method	Path
GET	/v1/consents/me
GET	/v1/consents/users/{user}
GET	/v1/consents/users/{user}/history

OpenAPI specification

A machine-readable OpenAPI 3.1 spec for every endpoint above is available at /docs/api.json. It is the source of truth used to generate the official SDKs. Generate a client in any language with openapi-generator or Kiota.