Pimcore (Digital Asset Management) API

Authentication

Datahub GraphQL (API key) S62 S63 S67

1. In Studio, create a Datahub configuration of type GraphQL. Under Security Settings, click Generate Key; each click adds a key, so several keys can be valid at once.
2. Select the workspaces (asset folders) and the create/read/update/delete rights the endpoint may use. With no workspace, nothing is accessible.
3. Send the key with each request as an apikey header, an X-API-Key header or an ?apikey= query parameter.
4. Optional: disable introspection, or set what happens to related elements outside the workspace (fail the query, or null them out — the default).

Datahub Simple REST (API key or OAuth) S70

• Delivery Settings tab: define or generate an API key, sent as a bearer token in a header with every request. The same key secures the MCP endpoint.
• OAuth Access: allow chosen Pimcore users and roles to call the endpoint with tokens from the embedded OAuth 2.1 server. REST and MCP are separate audiences, so a token for one is refused by the other.

Studio Backend API (session) S60 S59

• POST/pimcore-studio/api/login with credentials. With 2FA, the code follows on POST/pimcore-studio/api/login/2fa. POST/pimcore-studio/api/login/token logs in with a user token; POST/pimcore-studio/api/logout ends the session.
• The OpenAPI file declares no security scheme S60. Calls rely on the session cookie set at login. Real-time updates go through a Mercure hub (POST/pimcore-studio/api/mercure/auth) S59 S60.
• The API exists mainly to serve the Studio UI. Pimcore's Datahub docs separate the Studio API used by configuration panels from the endpoints meant for external systems S62 S70.

Embedded OAuth 2.1 authorization server (Studio Backend, experimental since 2026.3, off by default) S57 S11

• Discovery: /.well-known/oauth-authorization-server (RFC 8414) and /.well-known/oauth-protected-resource{/path} (RFC 9728).
• Flow: /pimcore-oauth/authorize sends the user to a consent screen in Studio, then /pimcore-oauth/token exchanges the code for tokens (authorization_code and refresh_token grants). PKCE S256 is required from every client; plain is refused.
• Clients: pre-registered in config, optional Dynamic Client Registration (/pimcore-oauth/register, RFC 7591), or Client ID Metadata Documents. There is no client-credentials grant: tokens always act for a logged-in user. Machine access uses API keys or PATs instead.
• The issuer must be the root of an origin; installations under a path prefix are not supported. The token and authorize endpoints have no rate limit.

MCP endpoints S56

• Stateless pimcore_mcp firewall on /pimcore-mcp/. It tries, in order: the Studio session cookie, Bearer pmcp_… per-chat tokens (minted by the Pimcore AI agent server, SHA-256 hashed at rest, sliding expiry), Bearer <JWT> from the OAuth server, then static personal access tokens declared per username in YAML.
• Unauthenticated calls get 401. When OAuth is on, the response carries a WWW-Authenticate header pointing at the protected-resource metadata.

WebDAV: any Pimcore user, with that user's asset permissions S31.

Core resources

Studio Backend API paths below are relative to https://{host}. They come from the OpenAPI file (version 2026.2): 683 paths, 815 operations (406 GET, 225 POST, 91 DELETE, 85 PUT, 8 PATCH) in 66 tags. 377 of these operations belong to Enterprise or optional bundles, so the routes available depend on what is installed S60.

Exact per-config Simple REST paths and parameters are documented in each instance's Swagger UI, which was not reachable without an instance S69.

Data model

• Elements: Assets, Data Objects and Documents are the three element types. Each element has an integer ID, a full path in its tree (/folder/file.jpg), a type and timestamps S95 S60.
• Asset types: image, video, audio, document, text, archive, folder and unknown (the default list in webhook schemas) S74. GET/pimcore-studio/api/assets/types returns the installed list S60.
• Metadata: a list of entries (name, input type, language, data), localizable, with fallback to the unlocalized value (e.g. addMetadata("title", "input", "…", "en")) S32. The full list of core metadata types is not stated on that page: Unknown. Enterprise class definitions add structured schemas and more data types S42. Embedded EXIF/IPTC/XMP is exposed read-only S26.
• Files & renditions: one binary per asset in Flysystem storage. Renditions ("thumbnails") are generated from named configurations, on demand or deferred, and stored in their own storage S33 S27.
• Taxonomy: hierarchical tags (ID, name, parentId, idPath), inheritable properties and folder paths S35.
• Relations: data objects link to assets through relation fields. Dependencies are tracked both ways S60 S95.
• Versions: serialized snapshots with optional notes S34 S32.

Search & querying

• PQL (Studio API pqlQuery, Copilot filters): comparisons, LIKE with */? wildcards (case-insensitive), NULL/EMPTY, AND/OR with brackets, relation filters such as main_image:Asset.type = "image", raw QUERY('…') S43.
• GraphQL: filter takes a JSON condition ($like, $and, $or, …) in Pimcore's webservice filter syntax; sortBy/sortOrder; totalCount S66 S64.
• Simple REST: fulltext_search (OpenSearch simple_query_string), query_string_query for field filters, legacy JSON filter, order_by (string or JSON with unmapped_type), and aggregations for facets configured per endpoint. Without order_by, results come by relevance (full-text) or by system.id S71 S70.
• Max page size: Studio API: Not public (no maximum stated in the spec). Simple REST MCP tools clamp to 1–200 S72. Deep paging through page_cursor / search_after S71.
• Semantic search through embeddings (Enterprise, experimental), behind a dedicated permission S11 S41.

Uploads & binaries

• Studio API: multipart/form-data upload with a file field (and optional assetType) to /pimcore-studio/api/assets/add/{parentId}. ZIP import and binary replacement have their own endpoints S60. Chunked or resumable upload: Not public (no such endpoint in the spec).
• GraphQL: createAsset / updateAsset take the file as base64 in input.data. The parent must be in a workspace with create rights S65.
• WebDAV: PUT/GET through any WebDAV client S31.
• Downloads: public assets and thumbnails are plain URLs served by the web server (with optional CDN prefixes). Protected folders need a custom controller S30 S33. Studio API download and stream endpoints need a session S60. Simple REST download-asset only hands out variants allowed by the endpoint configuration S70.
• Presigned URLs: Not public (none documented).
• Server upload limits follow PHP settings (≥ 100 MB recommended) S36.

Events & webhooks

• Datahub Webhooks (Enterprise) S73 S74 S75 S76 S77:
  • Events: pimcore.asset.postAdd (POST), postUpdate (PUT), postDelete (DELETE), postUpdateFailure, postDeleteFailure, and the same for data objects and documents; workflow.entered, workflow.completed (PUT).
  • Configured in the Studio UI per Datahub configuration: asset types, workspaces, optional binary data (original or a thumbnail, base64 in data64), subscriber URLs, custom headers (e.g. an auth header). A test button checks reachability.
  • Payload: general (eventName, timestamp, subjectType, versionOnly) and subject (id, path, type, mimeType…), plus workflowData for workflow events.
  • Delivery goes through a Symfony Messenger queue and is attempted once: a subscriber that was down does not get the event later. Failures appear in the configuration's Logs tab. No payload signature is documented. Auto-saves never trigger webhooks.
• Server-side events: Pimcore and Symfony event listeners (e.g. asset pre/post save) for custom code S74 S59.
• Real-time UI updates: Mercure server-sent events S59.
• Workflow Automation (Enterprise) exports n8n blueprints built from GraphQL and webhook configurations S79.

Limits & quirks

• Rate limits apply to the Studio API and MCP only: 500/min and 3,000/min per IP by default. Behind a proxy, trusted proxies must be configured or all users share one bucket. Multi-server setups need a shared cache (e.g. Redis) for the limiter S58.
• Assets are public by URL by default: an API permission model does not protect a file's direct URL unless protected folders are set up S30.
• GraphQL API keys in the query string are supported, so keys can end up in access logs. Header-based keys (apikey, X-API-Key) are also accepted S62 S67.
• "Skip Permission Check" disables workspace checks entirely for a GraphQL endpoint S63.
• Simple REST is eventually consistent: it serves the search index, so new configuration changes need re-indexing. binaryData links can point to variants no longer published until re-indexing. For SVGs, a non-rasterizing thumbnail exposes the original S70.
• GraphQL output cache (off by default, 30 s default lifetime when on) can serve stale data S62.
• Datahub config storage: YAML files are only re-read in debug mode, so production changes must be deployed S68.
• OAuth server is experimental: configuration keys may change between minor versions S57.
• Studio API is shaped around the UI (grids, perspectives, widgets), declares no security scheme in OpenAPI, and depends on Mercure and the Generic Data Index S60 S59.
• Enterprise source is private: Simple REST, Webhooks, Portal Engine, Direct Edit and Copilot repositories are not public on GitHub S90.

SDKs, tools & code samples

Changelog of the API