Content API | Version 3

Content API Guide

With the Sophora Content API developers can retrieve content from Sophora in JSON format via HTTP. Write and edit operations are also possible.

Archived documentation for Sophora 3. End-of-support date for this version: 7/25/21

Documentation for Sophora 4

Getting Started

The Content API in the Sophora Server is accessible via HTTP and HTTPS. All types of Sophora Servers are able to respond to requests.

The base url for all URLs is: http://hostname:1196/content-api

The port can be configured with the property: sophora.remote.api.http.port

All responses of requests are in JSON format.


To access the Content API a HTTP basic authentication with user name and password is required. All Sophora users can assess this API with their normal password.

Swagger Example Documentation

Have a look at the Swagger documentation of Sophora's Content API running in the Sophora Demo Website.

Sophora Content API: Swagger Docs (Demosite)
Sophora Content API: Swagger Docs (Demosite) (Image: subshell/CC BY)


Authentication: guest/guest


The Content API is configured in the file, which must be located in the folder ${sophora.home}/config. A changed configuration is at first effective after a restart of the application.
Configuration KeyDescriptionDefault
content-api.client.documentCacheSizeDefines the size of the document cache. The Content API internally maintains one Sophora Client and therefore one individual document cache for each logged in user. By choosing the size of the document cache, the estimated number of concurrently logged in users must be considered.50
content-api.textlinks.includeReferenceIs relevant for the http endpoints underneath the path /content/.

If switched to true, the Content API URLs of referenced documents within a text link are additionally added to the corresponding anchor html element.
content-api.baseUrlIs only relevant for the HTTP endpoints underneath the path /content/.

Defines the external URL of the Content API. The configuration parameter is used for the url of referenced documents within anchor elements of text links. It is only relevant if content-api.textlinks.includeReference is set to true.
Take the configuration http://my.server.domain:1196/content-api as an example. The generated anchor element of a text link would be: <a data-reference-url="http://my.server.domain:1196/content-api/content/document/50fc8c22-56d1-4155-885a-19fb0790e6f1 ... \> ... </a>
(Empty String)
content-api.isLiveIs only relevant for the http endpoints underneath the path /content/.

Defines whether the Content API is used for a live or preview delivery. If set to true, time schedules and offline documents are regarded. Otherwise not (due to preview).
content-api.domainIs only relevant for the http endpoints underneath the path /content/.

Defines the domain of the href urls of anchor elements of text links.
Take the configuration as an example. The generated anchor element of a text link would be: <a href="" ... > ... </a>
(Empty String)

Examples of the HTTP Endpoints

Please refer the Swagger documentation for an comprehensive overview of the provided HTTP endpoints.

Accessing and browsing documents

GET /browse/{structure/node/path}To browse through documents you need to set the structurenodepath to the URL. It will return all documents and structurenodes under the given path. It will not return documents and structure nodes recursively.
GET /document/{uuid}This url needs the documents UUID. It will return the document with the UUID.
GET /documentBySophoraId/{sophoraId}This url needs the Sophora ID. It will return the document with the Sophora ID.
GET /documentByExternalId/{externalId}This url needs the External-Id. It will return the document with the External ID. The API endpoint where the External ID is passed as a part of the url path does not support slashes in the External ID. If your External IDs contain slashes please use the same-named query parameter externalId instead.
  • Example with path variable:
  • Example with query parameter:

Browsing documents

Resource URL:{StructureNodePath}

searchValue*search termsearchValue=bread
searchFieldFind the search term in the given searchFieldsearchField=fieldA&searchField=fieldB
solrSearchFieldssearchField_t:, copytext_t:, childnode_content_t:Find the given search term in the given solrSearchFieldssolrSearchFields=fieldA&solrSearchFields=fieldB
pageIndex0The pageIndex starts with an index 0pageIndex=1
pageSize1000The pageSize is the number of documents per pagepageSize=10
sortFieldTo order the result set a field to ordersortField=sophora:createdBy
sortDirectionascSets the direction of the order ascending or descending. Valid values are asc and desc. If an invalid value was set the order is ascsortDirection=desc

The example response looks like this:

   "totalEntriesCount": 15,
   "pageCount": 1,
   "pageIndex": 0,
   "pageSize": 1000,
   "documents": [
         "jcr:primaryType": "sophora-content-nt:audio",
         "jcr:uuid": "bd774658-f980-4ad2-a17e-04572aeb0286",
         "_structureNodePath": "/demosite",
         "_url": "",
         "_structureNodeUrl": "",
         "isDocumentSummary": true,
         "sophora-content:shorttext": "Karl Lagerfeld's Sewing Machine ...",
         "sophora-content:taxo": [
            "Karl Lagerfeld"
         "sophora-content:title": "Sewing Machine",
         "sophora-content:topline": "Karl Lagerfeld:",
         "sophora:createdBy": "admin",
         "sophora:creationDate": "2010-06-29T11:18:00.648Z",
         "sophora:externalId": "944b4059-5b88-4088-93ed-f0b93121cdec",
         "sophora:id": "audio100",
         "sophora:isOnline": true,
         "sophora:liveStructureNode": "b6d3cf76-b114-4e6c-95da-2033a413c08e",
         "sophora:modificationDate": "2014-08-28T09:46:43.530Z",
         "sophora:modifiedBy": "admin",
         "sophora:publicationDate": "2014-08-28T09:46:43.530Z",
         "sophora:publishedBy": "admin",
         "sophora:site": "b6d3cf76-b114-4e6c-95da-2033a413c08e",
         "sophora:state": "published",
         "sophora:structureNode": "b6d3cf76-b114-4e6c-95da-2033a413c08e",
         "sophora:tags": "lagerfeld sewing machine audio"
   "structure": {
      "path": "demosite",
      "structure": [
            "name": "home",
            "uuid": "c7ad6486-b35b-4e16-9cec-c3b26332580d",
            "hasChildren": false
            "name": "trendcities",
            "uuid": "05621d7b-585d-471d-8604-538c0b315880",
            "hasChildren": true
            "name": "forecasts",
            "uuid": "e40a400a-38d9-4b3b-95b6-2de2a1228892",
            "hasChildren": true
            "name": "timeline",
            "uuid": "4e543a81-48c1-4622-b03f-690da3490cf3",
            "hasChildren": false
            "name": "video",
            "uuid": "d7bf6ab7-d248-4ab8-9955-134c2098ce27",
            "hasChildren": false

Accessing a document

Example URL:

The response looks like this:

     "jcr:primaryType": "sophora-content-nt:story",
     "jcr:uuid": "a3051af2-c506-4c8e-99f2-a2b14bda9f39",
     "jcr:mixinTypes": [
    "sophora:createdBy": "admin",
    "sophora:creationDate": "2013-02-22T08:53:31.139Z",
    "sophora:externalId": "a3051af2-c506-4c8e-99f2-a2b14bda9f39",
    "sophora:id": "test106",
    "sophora:modificationDate": "2013-02-22T08:53:31.139Z",
    "sophora:modifiedBy": "admin",
    "sophora:originalDocument": "a7e6ec4e-9f7b-4b8d-a296-1ab177930400",
    "sophora:site": "b6d3cf76-b114-4e6c-95da-2033a413c08e",
    "sophora:state": "inProcess",
    "sophora:structureNode": "b6d3cf76-b114-4e6c-95da-2033a413c08e",
    "sophora:tags": "kopie kopie kopie",
    "sophora-content:copytext": {
        "jcr:primaryType": "sophora-extension-nt:copytext",
        "sophora-extension:paragraph": {
            "jcr:primaryType": "sophora-extension-nt:paragraph",
            "sophora-extension:style": "paragraph",
            "sophora-extension:text": "",
            "sophora:childNodeId": -8701503074510348000

Saving a Document

Example URL (Method: POST):

The request parameter idStem is optional. The document to be saved must be passed as the request body in the JSON format.

Accessing and manipulating Structurenodes

POST /structure/{structurepath}Creates a new structurenode under the given path
GET /structure/{structurepath}Returns all structurenodes under the given path. It does not return structurenodes recursively
DELETE /structure/{uuid}Deletes the structurenode with the given uuid

Lock State

It is possible to access the lock state of a document. This is possible by adding /lockState to the three types of document URLs:

  • /content-api/document/{uuidStr}/lockState
  • /content-api/documentBySophoraId/{sophoraId}/lockState
  • /content-api/documentByExternalId/{externalId}/lockState

The JSON response for a locked document looks like this:

    "documentUuid": "a3051af2-c506-4c8e-99f2-a2b14bda9f39",
    "locked": true,
    "lockedBy": "admin",
    "lockDate": 1362054047011,
    "lockOwnerClientId": "90c33a40-7855-4fb4-9b58-7558ed42ea64"

The JSON response for a document without a lock looks like this:

    "documentUuid": "a3051af2-c506-4c8e-99f2-a2b14bda9f39",
    "locked": false

Nodetype Configurations

Example URL:{nodetypename}

List of all connected Sophora Servers

Example URL:

List of all connected tools

Example URL:

Last modified on 9/9/20

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.