Warning: You are browsing the documentation from version 4 to 10 of Pimcore. Please visit https://pimcore.com/docs/platform/ for the latest versions of Pimcore.

Version:

REST Webservice API

Pimcore provides a REST web service interface to many entities of the system, such as assets, documents, objects, class definitions, translations, etc. The webservices are not enabled by default, you have to do this in Settings > System Settings > Web Service API.

Once the web service API is enabled, there is an API key displayed in Settings > Users for each user. Please be aware that the API Key changes when the user changes his/her password.

The webservices also support session authentication, this means that it's not necessary to add the apikey to the request if you have a valid user session from the admin interface (eg. when testing in the browser).

Important: Import/export topics
The webservice API is not always the preferred way for importing/syncing data out of or into Pimcore. Often it's much more efficient to use the PHP API in custom scripts (CLI) or in a custom service endpoint. Please have a look at the following topics before your're seriously considering using the REST API: External System Interaction, Console CLI, Working with the PHP API.

Important: Frontend Applications
The Pimcore REST API is not intended to be used as a data provider for frontend applications (Vue.js, React, Angular, ...), please build your own actions for that purpose or use any existing bundles.

REST Webservice API

Permissions

Unrestricted access is only granted to admin users. For all other users the following restrictions are enforced:

Classes permission for the following calls:
- Classes list
- Object bricks list
- Field Collections list
- Class Definition
- Object Brick Definition
- Field collection Definition
- Key Value Definition
- Object metadata
Asset permission:
- Asset List
- Asset Count
- Tags for Element (element of type Asset)
- Elements for Tag (element of type Asset)
Document permission
- Document List
- Document Count
- Tags for Element (element of type Document)
- Elements for Tag (element of type Document)
Object permission
- Object List
- Object Count
- Tags for Element (element of type Object)
- Elements for Tag (element of type Object)
Tags search permission
- Tag List
- Tags for Element
- Elements for Tag
System Settings Permission
- Get Server Info
Workspace View permission
- Get Asset|Document|Object
Workspace Delete permission
- Delete Asset|Document|Object
Workspace Create permission
- Create Asset|Document|Object
Workspace Save permission
- Publish Asset|Document|Object

Available Calls

The following methods are available for web service calls:

Get Object By ID

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/object/id/1281?apikey=[API-KEY]&inheritance=0
Optional parameter inheritance decides whether to enable inheritance or not (disabled by default). See
Returns: JSON-encoded object data.

Delete Object By ID

Method: DELETE
URL: http://YOUR-DOMAIN/webservice/rest/object/id/1281?apikey=[API-KEY]
Returns: JSON-encoded success value

Create a new Object

Method: PUT or POST
URL: http://YOUR-DOMAIN/webservice/rest/object?apikey=[API-KEY]
Request body: JSON-encoded object data in the same format as returned by get object by id for the data segment but with missing id field. Check the example below for the correct structure.
Returns: JSON-encoded object id

Example:

{
	"className": "Product",
	"parentId": <SOME_PARENT_ID>,     
	"key": "Grey t-shirt",
	"elements": [       
	    {         
	        "type": "input",         
	        "value": "Grey T-Shirt",         
	        "name": "name",         
	        "language": null
        },{
             "type": "multiselect",         
             "value": "grey",
             "name": "color",
             "language": null
        }     
    ],
	"notes": [
        {
            "type": "warning",
            "title": "API test",
            "description": "<b>Testing the api</b>",
            "data": []
        }
    ]
}

Update existing Object

Method: PUT or POST
URL: http://YOUR-DOMAIN/webservice/rest/object?apikey=[API-KEY]
Request body: JSON-encoded object data in the same format as returned by get object by id for the data segment but with missing id field. Check the example below for the correct structure.
Returns: JSON-encoded success value

Example:

{
	"className": "Product",
	"parentId": <SOME_PARENT_ID>, 
	"id": 8812,    
	"key": "Grey t-shirt",
	"elements": [       
	    {         
	        "type": "input",         
	        "value": "Grey T-Shirt",         
	        "name": "name",         
	        "language": null
        },{
             "type": "multiselect",         
             "value": "grey",
             "name": "color",
             "language": null
        }     
    ],
	"notes": [
        {
            "type": "warning",
            "title": "API test",
            "description": "<b>Testing the api</b>",
            "data": []
        }
    ]
}

Check Object exists

Method: GET or POST
URL for GET: http://YOUR-DOMAIN/webservice/rest/object-inquire?apikey=[API-KEY]&ids=4500,4501,2,9999&condense=0
- ids Parameter for GET: comma-seperated list of object ids
URL for POST: http://YOUR-DOMAIN/webservice/rest/object-inquire?apikey=API-KEY&condense=0
- Request body for POST: comma-seperated list of object ids
Returns: JSON-encoded success value and list of object ids and flag indicating whether object exists or not. If optional condense parameter is set to true then only non-existing object ids are returned.

Example:

{
  "success": true,
  "data": {
    "4500": 1,
    "4501": 1,
    "2": 1,
    "9999": 0
  }
}

Get Object Metadata

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/object-meta/id/1281?apikey=[API-KEY]

Get List of Classes

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/classes?apikey=[API-KEY]
Returns: The JSON-encoded list of classes

Get Class By ID

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/class/id/1281?apikey=[API-KEY]
Returns: The JSON-encoded class definition for the given class

Get List of Field Collections

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/field-collections?apikey=[API-KEY]
Returns: The JSON-encoded list of field collection configurations

Get Field Collection Definition By Key

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/field-collection/id/collectionA?apikey=[API-KEY]
Returns: The JSON-encoded field collection definition for the collection with the given key

Get List of Field Object Bricks

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/object-bricks?apikey=[API-KEY]
Returns: The JSON-encoded list of object brick configurations

Get Object Brick Definition By Key

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/object-brick/id/tirebrick?apikey=[API-KEY]
Returns: The JSON-encoded object brick definition for the object brick with the given key

Get List of Image Thumbnail Configurations

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/image-thumbnails?apikey=[API-KEY]
Returns: The JSON-encoded list of image thumbnail configurations

Get Image Thumbnail Configuration By Key

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/image-thumbnail/id/product_small?apikey=[API-KEY]
Returns: The JSON-encoded image thumbnail configuration with the given key

Get Asset By ID

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/asset/id/1281?apikey=[API-KEY]
Optional Parameter: light if set to true, the response will not contain the data (base64) of the asset.
Returns: JSON-encoded asset data.

Delete Asset By ID

Method: DELETE
URL: http://YOUR-DOMAIN/webservice/rest/asset/id/1281?apikey=[API-KEY]
Returns: JSON-encoded success value

Create New Asset

Method: PUT or POST
URL: http://YOUR-DOMAIN/webservice/rest/asset?apikey=[API-KEY]
Request body: JSON-encoded asset data in the same format as returned by get asset by id for the data segment but with missing id field or id set to 0
Returns: JSON-encoded asset id

Example:

{
	"data": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsBAMAAACLU5NGAAAAG1BMVEXMzMyWlpa...",
	"parentId": 7, 
	"type": "image",    
	"filename": "rest-uploaded-file.jpg",
}

Update Existing Asset

Method: PUT or POST
URL: http://YOUR-DOMAIN/webservice/rest/asset?apikey=[API-KEY]
Request body: Same as for create asset but with asset id
Returns: JSON-encoded success value

Check Asset exists

Method: GET or POST
URL for GET: http://YOUR-DOMAIN/webservice/rest/asset-inquire?apikey=[API-KEY]&ids=4500,4501,2,9999&condense=0
- ids Parameter for GET: comma-seperated list of asset ids
URL for POST: http://YOUR-DOMAIN/webservice/rest/asset-inquire?apikey=[API-KEY]&condense=0
- Request body for POST: comma-seperated list of asset ids
Returns: JSON-encoded success value, list of asset ids and flag indicating whether asset exists or not. If optional condense parameter is set to true then only non-existing asset ids are returned.

Get Document By ID

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/document/id/1281?apikey=[API-KEY]
Returns: JSON-encoded document data.

Delete Document By ID

Method: DELETE
URL: http://YOUR-DOMAIN/webservice/rest/document/id/1281?apikey=[API-KEY]
Returns: JSON-encoded success value

Create New Document

Method: PUT or POST
URL: http://YOUR-DOMAIN/webservice/rest/document?apikey=[API-KEY]
Request body: JSON-encoded document data in the same format as returned by get document by id for the data segment but with missing id field or id set to 0
Returns: JSON-encoded document id

Update Existing Document

Method: PUT or POST
URL: http://YOUR-DOMAIN/webservice/rest/document?apikey=[API-KEY]
Request body: Same as for create document but with object id
Returns: JSON-encoded success value

Check Document exists

Method: GET or POST
URL for GET: http://YOUR-DOMAIN/webservice/rest/document-inquire?apikey=[API-KEY]&ids=4500,4501,2,9999&condense=0
- ids Parameter for GET: comma-seperated list of document ids
URL for POST: http://YOUR-DOMAIN/webservice/rest/document-inquire?apikey=[API-KEY]&condense=0
- Request body for POST: comma-seperated list of document ids
Returns: JSON-encoded success value, list of document ids and flag indicating whether document exists or not. If optional condense parameter is set to true then only non-existing documentids are returned.

Search Assets

Method: GET
URL: `http://YOUR-DOMAIN/webservice/rest/asset-list?apikey=[API-KEY]&order=DESC&offset=3&orderKey=id&limit=2&q={"type":%20"folder"}
Returns: A list of asset id/type pairs matching the given criteria.
Parameters:
- q: "Query Filter
- order: sort order (if supplied then also the key must be provided)
- orderKey: sort order key
- offset: search offset
- limit: result limit
- groupBy: group by key

Search Documents

Method: GET
URL: `http://YOUR-DOMAIN/webservice/rest/document-list?apikey=[API-KEY]&order=DESC&offset=3&orderKey=id&limit=2&q={"type":%20"folder"}
Returns: A list of document id/type pairs matching the given criteria.
Parameters:
- q: "Query Filter
- order: sort order (if supplied then also the key must be provided)
- orderKey: sort order key
- offset: search offset
- limit: result limit
- groupBy: group by key

Search Objects

Method: GET
URL: `http://YOUR-DOMAIN/webservice/rest/object-list?apikey=[API-KEY]&order=DESC&offset=3&orderKey=id&limit=2&objectClass=myClassname&q={"o_type":%20"folder"}
Returns: A list of object id/type pairs matching the given criteria.
Parameters:
- q: "Query Filter
- order: sort order (if supplied then also the key must be provided)
- orderKey: sort order key
- offset: search offset
- limit: result limit
- groupBy: group by key
- objectClass: the name of the object class (without "DataObject"). Note: If the class does not exist the filter criteria will be ignored!

Get Asset Count

Method: GET
URL: `http://YOUR-DOMAIN/webservice/rest/asset-count?apikey=[API-KEY]&q={"type":%20"folder"}
Returns: The total number of assets matching the given criteria.
Parameters:
- q: "Query Filter
- groupBy: group by key

Get Document Count

Method: GET
URL: `http://YOUR-DOMAIN/webservice/rest/document-count?apikey=[API-KEY]&q={"type":%20"folder"}
Returns: The total number of documents matching the given criteria.
Parameters:
- q: "Query Filter
- groupBy: group by key

Get Object Count

Method: GET
URL: `http://YOUR-DOMAIN/webservice/rest/object-count?apikey=[API-KEY]&q={"type":%20"folder"}
Returns: The total number of objects matching the given criteria.
Parameters:
- q: "Query Filter
- groupBy: group by key
- objectClass: the name of the object class (without "DataObject"). Note: If the class does not exist the filter criteria will be ignored!

Get List of Tags

Method: GET
URL: http://[YOUR-DOMAIN]/webservice/rest/tag-list?apikey=[API-KEY]
Returns: The JSON-encoded list of tags.

Get Tags for an Element

Method: GET
URL: http://[YOUR-DOMAIN]/webservice/rest/tags-element-list?apikey=[API-KEY]&id=1281&type=object
Returns: The JSON-encoded list of tags ids for the element.
Parameters:
- id: element id
- type: type of element (document | asset | object)

Get Elements for a Tag

Method: GET
URL: http://[YOUR-DOMAIN]/webservice/rest/elements-tag-list?apikey=[API-KEY]&id=12&type=object
Returns: The JSON-encoded list of elements id/type pairs matching the given tag.
Parameters:
- id: tag id
- type: type of element (document | asset | object)

Get User

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/user?apikey=[API-KEY]
Returns: The JSON-encoded user data for the current user

Get Server Info

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/server-info?apikey=[API-KEY]
Returns: The JSON encoded server-info including Pimcore version, current time and extension data.

Get Server Time

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/system-clock?apikey=[API-KEY]
Returns: The JSON encoded system time.

Translations

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/translations?apikey=[API-KEY]&type=website
Returns: List of translations.
Parameters:
- type: "website" or "admin" (required)
- key: tranlation key matches param
- creationDateFrom: timestamp
- creationDateTill: timstamp

Get Classification Store Definition

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/classificationstore-definition?apikey=[API-KEY]
Returns: The JSON-encoded classification store definition
Parameters:
- q: "Query Filter

Get QuantityValue unit Definition

Method: GET
URL: http://YOUR-DOMAIN/webservice/rest/quantity-value-unit-definition?apikey=[API-KEY]
Returns: The JSON-encoded list of QuantityValue unit definitions
Parameters:
- q: "Query Filter

Override HTTP Method

The HTTP request method can be overwritten by providing a method parameter.

Method: any
URL: http://YOUR-DOMAIN/webservice/rest/object/id/1281?apikey=[API-KEY]&method=PUT