DMS REST API

This reference describes the classic centraQuest DMS JSON REST webservice API. It is based on the original centraQuest DMS Webservice API Description, version 1.0, November 2020.

Source document: centraQuest DMS API Description 1.0

Scope

The DMS REST API exposes core document management functions over HTTP. It is designed so that browser-based clients can call the API directly without a dedicated client library.

The server-side API used internally for jobs, triggers, and templates is not covered here.

Base URL

API functions are addressed by relative URLs below the server root:

https://<hostname>[:port]/<function-url>

Example:

https://<hostname>/dms/login?user=<user>&password=<password>

Most calls use an id parameter. In normal installations this is the GUID-style object ID of a document, folder, or other DMS object.

Authentication

All calls except dms/login require a valid session ticket. The ticket can be passed either as:

• URL parameter ticket=<ticket>
• HTTP cookie using the session cookie name returned by dms/login

Login

GET|POST /dms/login

Obtains a session ticket from user credentials.

Parameters:

Name	Required	Description
user	yes	Login user name.
password	yes	Password. The legacy document describes this as encrypted.

Successful response:

{
  "session-cookie-name": "centraquest",
  "ticket": "4fcede6817d984db9d686d7997f8a023"
}

Error response:

{
  "message": "Login failed",
  "id": "login-failed"
}

Logout

GET|POST /dms/logout

Invalidates the current session ticket. Sessions also time out automatically, but explicit logout is recommended.

Parameters:

Name	Required	Description
ticket	yes	Session ticket, unless supplied as cookie.

Successful response:

{
  "status": "ok"
}

SSO Login

GET|POST /dms/ssologin

Challenge-response based single sign-on entry point. It is usually used behind other mechanisms such as NTLM, Kerberos, or two-factor authentication and is not intended for direct public use.

Object Navigation

Children

GET /dms/children

Returns child objects of a parent object. For folders, this corresponds to the folder content. centraQuest objects can also have parent-child relations outside the folder use case.

Parameters:

Name	Required	Description
id	yes	Parent object ID. Use root for the root folder.
ticket	yes	Session ticket, unless supplied as cookie.

Result:

Returns a JSON array with metadata objects for each child. Typical fields include obj_id, obj_name, obj_profile, obj_mask, obj_permission, _children, _parent, obj_created, and obj_modified.

Example:

/dms/children?id=root&ticket=<ticket>

Properties

GET|POST /dms/properties

Reads or updates object metadata.

• GET returns the metadata of the object.
• POST with application/json updates properties.

Parameters:

Name	Required	Description
id	yes	Object ID.
ticket	yes	Session ticket, unless supplied as cookie.

Example:

/dms/properties?id=<id>&ticket=<ticket>

Content Operations

Content Download

GET /dms/content

Returns the binary content of a document object. The response body contains the file content and HTTP headers such as content type, content length, and content disposition are set accordingly.

Parameters:

Name	Required	Description
id	yes	Object ID.
ticket	yes	Session ticket, unless supplied as cookie.
lock	no	Optional lock behavior according to installation-specific handling.

Example:

/dms/content?id=<id>&ticket=<ticket>

Upload

POST /dms/upload

Uploads a file or adds a new version to an existing object. The request body must be multipart/form-data. The file parameter must be named FILE.

Additional form or URL parameters can be used to set metadata. Metadata parameter names must use the internal field IDs such as obj_name or obj_description.

Parameters:

Name	Required	Description
FILE	yes	Multipart file field.
id	no	Existing object ID. If supplied, the upload is added as a new version.
parent	no	Parent folder ID for a new object.
original_filename	no	Original file name.
version	no	Version number.
version_comment	no	Description of the uploaded version.
ticket	yes	Session ticket, unless supplied as cookie.

Simple HTML form pattern:

<form action="dms/upload" method="post" enctype="multipart/form-data">
  <input type="file" name="FILE" id="FILE">
  <input type="text" name="obj_name" value="<name of the document>">
  <input type="submit" value="Upload">
</form>

Example:

/dms/upload?id=<id>&version=2.0&version_comment=Hinweis&ticket=<ticket>

Locking and Version Safety

Checkout

GET|POST /dms/checkout

Places an exclusive lock on an object. While the lock exists, only the lock owner is allowed to modify the object.

Parameters:

Name	Required	Description
id	yes	Object ID.
ticket	yes	Session ticket, unless supplied as cookie.

Successful response:

{
  "status": "ok",
  "operations": [
    {
      "operation": "refresh",
      "id": "<id>",
      "properties": "dms/properties?id=<id>"
    }
  ]
}

Cancel Checkout

GET|POST /dms/cancel-checkout

Removes an exclusive lock created by dms/checkout.

Parameters:

Name	Required	Description
id	yes	Object ID.
ticket	yes	Session ticket, unless supplied as cookie.

Object Lifecycle Operations

Delete

GET|POST /dms/delete

Deletes an object or document.

Parameters:

Name	Required	Description
id	yes	Object ID.
ticket	yes	Session ticket, unless supplied as cookie.

Successful responses usually contain status: ok and UI operation hints such as remove.

Copy

GET|POST /dms/copy

Creates a copy of an existing object or document.

Parameters:

Name	Required	Description
id	yes	Source object ID.
ticket	yes	Session ticket, unless supplied as cookie.
metadata parameters	no	Optional replacement metadata for the copied object.

Example:

/dms/copy?id=<id>&obj_name=Test123&ticket=<ticket>

Relations and Folder Links

Create Relation

GET|POST /dms/create-relation

Creates a named relation between existing objects. For parent-child relations, the relation name is typically parent.

Parameters:

Name	Required	Description
id	yes	Child object ID.
parent	yes	Parent object ID.
name	no	Relation name, for example parent.
ticket	yes	Session ticket, unless supplied as cookie.

Example:

/dms/create-relation?id=<id>&parent=<parent_id>&name=parent&ticket=<ticket>

Delete Relation

GET|POST /dms/delete-relation

Deletes existing relations between objects.

Parameters:

Name	Required	Description
id	conditional	Child object ID.
parent	conditional	Parent object ID.
name	no	Relation name.
ticket	yes	Session ticket, unless supplied as cookie.

At least one side of the relation must be specified. The legacy document notes that only one of parent and id must be present for some deletion cases; verify behavior against the target installation.

Link

GET|POST /dms/link

Links an object to a folder.

Parameters:

Name	Required	Description
id	yes	Object ID.
parent	yes	Folder ID.
ticket	yes	Session ticket, unless supplied as cookie.

Example:

/dms/link?id=<id>&parent=root&ticket=<ticket>

Unlink

GET|POST /dms/unlink

Removes a folder link from an object.

Parameters:

Name	Required	Description
id	yes	Object ID.
parent	yes	Folder ID.
delete	no	If present, delete the object when it is no longer contained in any folder.
ticket	yes	Session ticket, unless supplied as cookie.

Example:

/dms/unlink?id=<id>&parent=root&ticket=<ticket>

DQL Operations

Execute DQL

GET|POST /dms/dql

Executes a DQL query. DQL stands for Document Query Language and is the SQL-inspired query language used by centraQuest DMS.

Parameters:

Name	Required	Description
query	yes	URL-encoded or form-urlencoded DQL query.
result_limit	no	Maximum number of returned rows.
include_info	no	If true, includes column metadata such as IDs, labels, types, and lengths.
ticket	yes	Session ticket, unless supplied as cookie.

Example:

/dms/dql?query=select+*+from+cq_document+where+obj_profile%3D%27cq_kreditor%27+order+by+dobj_created&include_info=true&result_limit=100&ticket=<ticket>

Execute Server-Side Query

GET|POST /dms/dql-query

Runs a server-side predefined DQL query by query ID. Optional parameters can be passed to the query.

Parameters:

Name	Required	Description
query	yes	ID of the server-side query.
result_limit	no	Maximum number of returned rows.
include_info	no	Include column metadata.
query parameters	no	Query-specific parameters.
ticket	yes	Session ticket, unless supplied as cookie.

Example:

/dms/dql-query?query=qryGetKeywords&parent=all&field=cq_department&profile=all&ticket=<ticket>

DQL Basics

DQL is similar to SQL, but the from clause uses DMS object classes rather than relational table names. The basic object class is object, which queries across all object and document classes.

The data model is object-oriented and supports multivalue fields and relations.

Examples:

select * from object

select obj_name as name, obj_id from object

select * from contract

select distinct obj_name, count(*) as cnt from object

select distinct obj_name, substring(foo,3,5) as cnt from object

select distinct obj_name from cqp_list order by Aobj_name limit 100

select * from object where obj_created >= DATE('2010-2-13') order by Dobj_created

select count(*) from object where obj_profile = 'cqp_list' and obj_name like '%a%'

Subqueries are supported:

select * from object
where obj_id in (
  select child_id from relation where name='related'
)

Updates are supported:

update cm_contract set obj_name = 'foo'

Objects can also be updated and linked with DQL:

update object set obj_name = 'foo' link '/Administration/archived' where status=5

Deletes are supported and must include a where clause:

delete contract objects where status=1

Standard Fields

Custom metadata fields can be defined per installation. The following built-in fields are commonly available:

Field	Description
obj_id	GUID of the object or document.
obj_name	Name or label of the object.
obj_created	Creation timestamp.
obj_modified	Last modification timestamp.
obj_owner_name	Owner of the object.
obj_profile	Profile name. Profiles define object behavior and UI presentation.
obj_lock_name	User name of the user who locked the object.
obj_hist_count	Number of versions.
obj_child_count	Number of linked child objects, usually relevant for folders.
obj_vstamp	Internal update counter for optimistic locking.
obj_mask	Base object type. Defines which fields are associated with the object.
obj_version	Version number, for example 1.0, 1.1.1, or 2.0.
obj_version_labels	Symbolic version labels such as draft, effective, or final. Multivalue field.
obj_version_comment	Free-text comment for a version.
obj_content	Reference to the stored content file.
obj_content_type	MIME type of document content.

Error Handling

The legacy API documentation describes error responses mainly as HTTP status 400 or 500, depending on the condition. Callers should therefore handle:

• non-2xx HTTP status codes,
• JSON error objects where available,
• permission-related failures,
• invalid or expired tickets,
• malformed DQL or invalid object IDs.

Implementation Notes

• Use HTTPS for all environments outside local development.
• Prefer cookie-based ticket handling for browser clients.
• Always call dms/logout when a technical session is no longer needed.
• Use result_limit for DQL calls to protect the server and client from large result sets.
• Use checkout and cancel-checkout consistently when editing binary document content.
• Validate installation-specific profile, mask, and field names before relying on metadata fields in integrations.