Home > Developer Documentation Center > Nuxeo Server > REST API > REST API Web Adapters
Nuxeo Server

REST API Web Adapters

Updated: March 31, 2025

Adapters and REST Resources

WebEngine, the JAX-RS Server used to serve the REST API, offers WebAdapters for the Document Model. The REST API leverages this concept to expose adapters on top of the Document REST endpoint.

A WebAdapter is a URL segment starting with @ which transforms the input resource so as to return another resource. The idea is to have a URL pointing to a Document and use the adapter to convert the Document into something else before the result is returned. The general syntax is:

http://NUXEO_SERVER/nuxeo/api/v1/id/{docId}/@adapter/{parameters}

http://NUXEO_SERVER/nuxeo/api/v1/path/{documentPath}/@adapter/{parameters}

The notion of adapter precedes the concept of Content Enricher. Some of the adapters presented here could be replaced by Content Enrichers.

Simple Document Adapters

Default adapters provided by default.

Adapter Usage and sample URL
@acl Returns the ACLs of the target Document
/api/v1/id/{docId}/@acl
@audit Returns audit trail records corresponding to the target Document
/api/v1/id/{docId}/@audit
@blob Returns the Blob corresponding to the Document attribute matching the XPath parameter
/api/v1/id/{docId}/@blob/{xpath}
@children Returns children of the target Document
Query parameters (optional) are by default:
page:0
pageSize:50
maxResult:nolimit
/api/v1/id/{docId}/@children
@convert Returns the conversion of a blob
Query parameters (must use one):
converter
type
format
/api/v1/id/{docId}/@convert?format=pdf
@pp Returns the result of the query corresponding to the named PageProvider. The target Document is used to provide the parameters of the PageProvider (SearchDocumentModel).
/api/v1/id/{docId}/@pp/{pageProviderName}
@rendition Returns the renditions of a blob
/api/v1/id/{docId}/@rendition/{renditionName}
@search Returns paged results of the query (full-text or NXQL)
Query parameters (optional) are by default:
orderBy:dc:title
page:0
pageSize:50
maxResult:nolimit
/api/v1/path/{docId}/@search?fullText=nuxeo&orderBy=dc:title /api/v1/path/{pathOfTheDoc}/@search?query=SELECT * FROM File
@task Returns the task instance you have permission to see
/api/v1/id/{docId}/@task
@workflow Returns workflow instances launched by current user
/api/v1/id/{docId}/@workflow

Group Adapters

Default adapters provided by default.

@users Returns the member users of a group
/api/v1/group/{groupId}/@users
@groups Returns the member groups of a group
/api/v1/group/{groupId}/@groups

Custom Adapters

You can contribute new WebAdapters using WebEngine.

Alternatively, use the @bo WebAdapter to leverage standard Nuxeo DocumentModelAdapters which you can define with the adapter extension point.

@bo Specify the custom adapter you wish to use
/api/v1/id/{docId}/@bo/{documentAdapterName}

Or use the @op adapter to access operations.

@op Pipe document as input for an operation or automation chain
/api/v1/id/{docId}/@op/{OperationName} /api/v1/path/{pathOfTheDoc}/@op/Chain.{myChain}

Piping

Adapters can be chained: the result of one adapter becomes the input of the next one.

Here is an example :

Sample URL

/api/v1/id/{docId}/@blob/file:content/@op/Blob.ToPDF

Examples

Getting the Children of a Given Document - @children

Example

GET http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@children?currentPageIndex=0&pagesize=20&maxResults=100

Response

{
  "entity-type": "documents",
  "isPaginable": true,
  "resultsCount": 1,
  "pageSize": 50,
  "maxPageSize": 1000,
  "currentPageSize": 1,
  "currentPageIndex": 0,
  "numberOfPages": 1,
  "isPreviousPageAvailable": false,
  "isNextPageAvailable": false,
  "isLastPageAvailable": false,
  "isSortable": true,
  "hasError": false,
  "errorMessage": null,
  "totalSize": 1,
  "pageIndex": 0,
  "pageCount": 1,
  "entries": [{
    "entity-type": "document",
    "repository": "default",
    "uid": "0178eb31-b1ca-49af-86b0-ff59d671dc91",
    "path": "/default-domain",
    "type": "Domain",
    "state": "project",
    "parentRef": "6db16630-9e06-42ba-8ce2-e5a0f14e9ee7",
    "isCheckedOut": true,
    "isVersion": false,
    "isProxy": false,
    "changeToken": "1481174085000",
    "title": "Domain",
    "lastModified": "2016-12-08T05:14:45.00Z",
    "facets": ["Folderish", "SuperSpace", "NotCollectionMember"]
  }]
}

Full-Text Search

GET http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@search?fullText=nuxeo&orderBy=dc:title

Response Example

{
  "entity-type": "documents",
  "isPaginable": true,
  "resultsCount": 2,
  "pageSize": 50,
  "maxPageSize": 0,
  "currentPageSize": 2,
  "currentPageIndex": 0,
  "numberOfPages": 1,
  "isPreviousPageAvailable": false,
  "isNextPageAvailable": false,
  "isLastPageAvailable": false,
  "isSortable": true,
  "hasError": false,
  "errorMessage": null,
  "totalSize": 2,
  "pageIndex": 0,
  "pageCount": 1,
  "entries": [{
    "entity-type": "document",
    "repository": "default",
    "uid": "7808880b-9a2d-4f91-89d8-1bc49f6ba526",
    "path": "/default-domain/templates/customerReferenceDOCX",
    "type": "TemplateSource",
    "state": "project",
    "parentRef": "6ef6675e-4ec8-4484-88f6-62651c7311ad",
    "isCheckedOut": true,
    "changeToken": "1430295774263",
    "title": "Customer reference using Word template",
    "lastModified": "2015-04-29T08:22:54.26Z",
    "facets": [
      "Versionable",
      "Commentable",
      "HasRelatedText",
      "Thumbnail",
      "Downloadable",
      "Template"
    ]
  }, {
    "entity-type": "document",
    "repository": "default",
    "uid": "fd63af66-07d4-4430-8b13-f17c25d2513a",
    "path": "/default-domain/templates/interventionStatement",
    "type": "TemplateSource",
    "state": "project",
    "parentRef": "6ef6675e-4ec8-4484-88f6-62651c7311ad",
    "isCheckedOut": true,
    "changeToken": "1430295774052",
    "title": "Delivery Statement",
    "lastModified": "2015-04-29T08:22:54.05Z",
    "facets": [
      "Versionable",
      "Commentable",
      "HasRelatedText",
      "Thumbnail",
      "Downloadable",
      "Template"
    ]
  }]
}

If the pointed resource is not a Folder, then the search is issued from the parent document.

NXQL Search

You can also make some direct NXQL queries with this endpoint, like this:

GET Request Body

GET http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@search?query=SELECT * FROM File

Response Example

{
  "entity-type": "documents",
  "isPaginable": true,
  "resultsCount": 4,
  "pageSize": 50,
  "maxPageSize": 0,
  "currentPageSize": 4,
  "currentPageIndex": 0,
  "numberOfPages": 1,
  "isPreviousPageAvailable": false,
  "isNextPageAvailable": false,
  "isLastPageAvailable": false,
  "isSortable": true,
  "hasError": false,
  "errorMessage": null,
  "totalSize": 4,
  "pageIndex": 0,
  "pageCount": 1,
  "entries": [{
    "entity-type": "document",
    "repository": "default",
    "uid": "38723e10-80f8-477d-bb5e-6dcd9cf76f9f",
    "path": "/default-domain/workspaces/templatesamples/intervention",
    "type": "InterventionStatement",
    "state": "project",
    "parentRef": "a05f7f31-6727-48db-b8d9-a89023135867",
    "isCheckedOut": true,
    "changeToken": "1430295774082",
    "title": "Sample Intervention Statement",
    "lastModified": "2015-04-29T08:22:54.08Z",
    "facets": [
      "Versionable",
      "Publishable",
      "Commentable",
      "TemplateBased",
      "HasRelatedText",
      "Downloadable"
    ]
  }, {
    "entity-type": "document",
    "repository": "default",
    "uid": "489819bd-f265-47a6-931a-236cd55f97ec",
    "path": "/default-domain/workspaces/templatesamples/spec",
    "type": "File",
    "state": "project",
    "parentRef": "a05f7f31-6727-48db-b8d9-a89023135867",
    "isCheckedOut": true,
    "changeToken": "1430295774195",
    "title": "Spec",
    "lastModified": "2015-04-29T08:22:54.19Z",
    "facets": [
      "Versionable",
      "Publishable",
      "Commentable",
      "TemplateBased",
      "HasRelatedText",
      "Thumbnail",
      "Downloadable"
    ]
  }]
}

Getting a Business Object

GET Request Body

GET http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@bo/BusinessBeanAdapter

Response

{
  "entity-type": "BusinessBeanAdapter",
  "id": "37b1502b-26ff-430f-9f20-4bd0d803191e",
  "type": "Domain",
  "title": "Default domain",
  "description": ""
}

Updating a Business Object

To update a business object, send a PUT request on the business object resource with its content data:

PUT Request Body

PUT http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@bo/BusinessBeanAdapter
{
  "entity-type": "BusinessBeanAdapter",
  "value": {
    "id": "37b1502b-26ff-430f-9f20-4bd0d803191e",
    "type": "Domain",
    "title": "Default domain",
    "description": "My new description"
  }
}

Creating a Business Object

To create a business object, issue a POST on the object resource with the name of the newly created document:

POST Request Body

POST http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@bo/BusinessBeanAdapter/{newName}
{
  "entity-type": "BusinessBeanAdapter",
  "value": {
    "type": "Note",
    "title": "A sample note",
    "description": "",
    "note": "The content of my note",
  }
}

Bridging Operations and Automation Chains

Sample POST Request Body

POST http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@op/{myOperation}
{
  "params": {
    "opParam": "value"
  }
}

The response will depend on the result of the automation chain.

Sample POST Request Body on a Document

POST http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheDoc}/@op/Chain.{myChain}
{
  "params": {
    "chainParam": "value"
  }
}

Sample POST Request Body on a List of Documents

POST http://NUXEO_SERVER/nuxeo/site/api/v1/path/{pathOfTheFolder}/@children/@op/Chain.myChain
{
  "params": {
    "chainParam": "value"
  }
}

Pay attention to the fact that document list adapters are paged. That means that the chain will run on all documents of the current page.

Related Documentation