Phraseanet API

Authentication

Phrasea (Keycloak) S28 S39 S67

1. Each Phrasea installation runs a Keycloak realm (default name phrasea) S34. OIDC discovery lives at https://keycloak.{domain}/realms/phrasea/.well-known/openid-configuration S67.
2. Interactive apps use the authorization-code flow (/protocol/openid-connect/auth → /protocol/openid-connect/token), which the Databox and Expose specs declare as their oauth security scheme S39 S40.
3. Machine-to-machine: Keycloak clients with service accounts (service_account scope) and the client-credentials grant S28 S67. Admins create clients and assign roles and scopes in the Keycloak admin console S28.
4. Send Authorization: Bearer {access_token} to api-databox.{domain} etc. S39.
5. Admin rights: Keycloak role admin (all services) or <service>-admin (one service); Super Admin can do everything S29.

Phraseanet 4.1 (built-in OAuth2) S44 S51

1. A user registers an application (name, callback URL) from the account settings, reached by clicking their login in the menu bar. Phraseanet returns a client ID and secret S44.
2. Authorization: GEThttps://{host}/api/oauthv2/authorize with response type code, token or code_and_token S44.
3. Token: POSThttps://{host}/api/oauthv2/token with grant_type=authorization_code. The password grant is allowed for highly trusted clients S44.
4. Pass the token as the oauth_token query parameter or in the Authorization header. HTTPS is required S44 S43.
5. Phraseanet can also delegate login to an OpenID Connect provider such as a Phrasea Keycloak (openid and ps-auth providers) S56 S57.

Core resources

Phrasea — Databox API (https://api-databox.{domain}), from the vendor demo OpenAPI S39 and the next branch source S79.

Phrasea — Expose API (https://api-expose.{domain}) S40: /publications (CRUD, /slug-availability/{slug}, /{id}/assets, /{id}/sort-assets), GET/publications/{publicationSlug}/assets/{assetSlug}, /assets (CRUD, /{id}/sub-definitions), /sub-definitions, /publication-profiles, /download-requests, /uploads.

Phrasea — Uploader API (https://api-uploader.{domain}): resources Asset, Commit, FormSchema, Target, TargetParams, MultipartUpload S66. Key routes: POST/commit, POST/commits/{id}/ack, POST/assets/{id}/ack, GET/targets/{id}/form-schema S79 S32.

Phraseanet 4.1 (paths relative to https://{host}/api/v1, /v2, /v3) S51 S46 S50

Data model

Phrasea S22 S39 S30

• Workspace → Collections (nested; an asset can sit in several) → Assets. Assets can be stories that contain other assets.
• Asset: owner, privacy level, tags, attributes (values of attribute definitions, multilingual, possibly multi-valued, possibly entities from an entity list), renditions (built from rendition definitions), a source File with versions, attachments, annotations and discussion threads.
• Integrations and workflows are attached to a workspace. Webhooks are global to a service S36.
• Identifiers: string IDs in the API (UUID-style; the spec types them only as strings) S39. Users and groups are Keycloak identities S28.

Phraseanet 4.1 S50 S46

• Databox (sbas_id / databox_id: a metadata database with its own structure) → Collections (base_id) → Records (record_id, unique within a databox).
• A record has a caption (metadata fields), status bits, sub-definitions (renditions such as thumbnail, preview and document) with permalinks, and can be a story.
• A record is identified by the pair {databox_id}/{record_id}.

Search & querying

Phrasea S31 S39 S35

• GET/assets with query (full text), conditions[] (AQL), workspaces[], parents[], collection, story, ids[], include_deleted, page.
• AQL examples: title STARTS WITH "Report" AND (@tag HAS ALL OF ("a","b") OR description IS EMPTY); location WITHIN CIRCLE (48.85, 2.35, "1500m"); dates with prefix matching (@createdAt IS "2024-03"). CONTAINS / STARTS WITH / ENDS WITH are case-insensitive unless CASE SENSITIVE is added. They work on the raw value, which is indexed up to 256 characters S31.
• Facets, sorting, suggestions (/assets/suggest), geo clusters (/assets/geo-clusters) and kNN similarity on CLIP embeddings S22 S30.
• Page size: limit, max 100 S35. The maximum depth of deep pagination is not documented (Unknown).

Phraseanet S50

• v3 POST/search/: query (full text with operators, e.g. dogs OR cats; empty = all), search_type (0 records, 1 stories), bases[] (collection IDs), paging with offset/limit or page/per_page (1–100, default 10), story_children_limit, include[] to add facets or story children (left out by default).
• v3 POST/searchraw/ returns raw search-engine results S50 S51.

Uploads & binaries

Phrasea

• Multipart upload S38 S39: POST/uploads starts the upload, POST/uploads/{id}/part returns the URL for the next part, the client PUTs the part to object storage, then the upload is completed and attached to an asset. DELETE/uploads/{id} cancels it. The source also has POST/uploads/{id}/parts (batch of part URLs) S38.
• Signed URLs: request signatures expire after 3,600 s for Databox and Expose and 600 s for Uploader by default (*_REQUEST_SIGNATURE_TTL). Optional CloudFront signed delivery (TTL 86,400 s) S34.
• Uploader commits: users upload files, then commit the batch. The target (Databox, Phraseanet or another endpoint) is notified (push) or polls GET/commits (pull). It downloads each asset with GET/assets/{id}/download and acknowledges with POST/commits/{id}/ack S32.
• Assets can also be created from a URL S22.

Phraseanet

• POST/api/v1/records/add/ (multipart file + base_id; nosubdefs skips rendition generation). Files may land in quarantine S48 S46.
• POST/api/v3/records/{base_id}/ creates a record S50.
• Downloads: sub-definition permalinks (/permalink/v1/{databox_id}/{record_id}/{subdef}/…?token=…) with url, page_url and download_url S50 S48.

Events & webhooks

Phrasea S36 S37 S30

• Entity webhooks: admins manage them in the service's admin back office (EasyAdmin CRUD). Each webhook has a URL, a list of events, an active flag, "verify SSL", a timeout (default 30 s) and a secret field.
• Events (Databox): {entity}:create, {entity}:update, {entity}:delete for asset, attribute, attribute_definition, collection, rendition, rendition_definition, rendition_policy, tag, workspace S37.
• Delivery: HTTP POST with JSON body {"event": …, "payload": …}; redirects are not followed. Failed deliveries are stored in a webhook log S36.
• Signature: Unverified none found. The secret field exists but the delivery code reviewed on 2026-10-29 does not send it or sign the body. Retries: none found in the delivery handler (Unknown).
• Workflow webhook (core.webhook integration): calls a configurable URL (method, options, optional inputs and origin) as a workflow step S30. Saved-search automations can also fire webhooks S79.
• Real time: WebSocket notifications to clients through Sockudo S22.

Phraseanet 4.1 S45 S53 S54 S55

• Configured per OAuth application: webhook URL, active flag, list of listened events (empty = all) S55 S54.
• Events in the code: record.created, record.edited, record.deleted, record.media_substituted, record.collection_changed, record.status_changed, record.subdef.created, record.subdef.creation_failed, record.subdefs.created, order.created, order.delivered, order.denied, user.created, user.deleted, user.registration.granted, user.registration.rejected, new_feed_entry S53. Unverified The public docs still say only new_feed_entry exists S45.
• Delivery: JSON POST with a Phraseanet/{version} User-Agent and a default timeout of 30 s. Events are only sent when the app creator has rights on the affected collection or record. Failed deliveries go to a retry queue up to a configured maximum, then are logged S54.
• Signature: the application model has an hmac_key column S55, but the webhook worker does not use it Unverified (inference from code); the docs say nothing about signing S45.

Limits & quirks

• Phrasea API doc on the demo vs the code: the demo instance's OpenAPI lacks some routes in the current source (/assets/{id}/similar, /saved-search-automations) S39 S79. Unverified The demo probably runs an earlier release; its version is not exposed.
• API Platform conventions: JSON-LD (application/ld+json) or plain JSON. PATCH takes application/merge-patch+json S35.
• Production readiness: Alchemy says its Docker Compose and Helm containers are "primarily designed for development and testing" and need hardening for production. It recommends managed PostgreSQL and S3 S27.
• Phraseanet v1 envelope: every response wraps meta (api_version, http_code, error_type, error_message…) and response. With JSONP the HTTP status is 200 and the real code sits in meta.http_code S43.
• Phraseanet v1 has no anonymous access; every call needs a token S43.
• Phraseanet v3 spec coverage: the spec documents 7 operations, while the v3 routes also include /monitor/data/, /databoxes/subdefs/ and a sub-definition service callback S50 S51.
• Breaking change history (Phraseanet): API 1.2 renamed fields and changed collection shapes; later versions were backward-compatible S48.
• Legacy runtime: Phraseanet 4.1 requires PHP 7.0 S59, which has been end-of-life since 2019-01-10 S69.

SDKs, tools & code samples

Changelog of the API