API

The primedocs Web API lets you query information and trigger document generation. The following interfaces are available:

• Admin API: manage primedocs resources.
• Connect API: trigger server-side document generation.
• Connect Session API: session-based document generation.

See Authentication for details on signing in to the API.

Base URL and routing

All endpoints are versioned and live under the route prefix /api/v3/{datasourceId}/…. In a standard installation the Web API is additionally mounted under the host path /webapi, so the full URL is composed as follows:

https://{instance}/webapi/api/v3/{datasourceId}/…

The {datasourceId} identifies the datasource to address.

Error handling

Successful calls respond with 2xx. The Web API answers failed calls with a problem document according to RFC 7807 with the media type application/problem+json. This applies to the Admin API, Connect API and Connect Session API, and also to errors that occur before the actual endpoint, for example during authentication or for an unknown datasourceId.

Example for a Connect without an Author element sent to POST …/Connect/Document:

{
  "type": "about:blank",
  "title": "Bad request",
  "status": 400,
  "detail": "Invalid connect: No Author is set. Add an Author element with a Profile Id to the connect.",
  "instance": "/api/v3/{datasourceId}/Connect/Document",
  "code": "Connect.Invalid",
  "correlationId": "0HN7ABCDEF:00000001"
}

Field	Description
type	Always about:blank.
title	Short summary of the status, e.g. Bad request.
status	HTTP status code of the response.
detail	Description of the error. For input and execution errors it states the reason and, where possible, the correction needed.
instance	Path that was called. Omitted if the path could contain confidential values.
code	Stable, machine-readable error code, see Error codes.
correlationId	Identifier of the call. The same value is in the X-Correlation-ID response header and in the server log.
errors (optional)	Further messages that detail does not already contain.
helpLink (optional)	Link to further documentation, if available.

Further fields are possible, for example unavailableConnectedServiceKeys for Connect.ConnectedServicesNotReady (see Connect Session API).

Status codes

Status	Meaning
400 Bad Request	Invalid input, e.g. malformed or incomplete Connect XML, a Connect without Author, invalid language codes or parameters that the endpoint explicitly checks (InvalidQuery, InvalidBody). The caller can fix the error. Unreadable query or route values do not lead to 400 everywhere.
401 Unauthorized	No or invalid access token, see Authentication errors.
403 Forbidden	The token does not have the required rights (scope/role) for the operation.
404 Not Found	The resource was not found, e.g. an unknown datasourceId, an unknown user or an expired session.
409 Conflict	The change conflicts with the current state, e.g. because of a concurrent change.
413 Payload Too Large	The request body exceeds the allowed size.
422 Unprocessable Entity	The request is valid but could not be carried out, e.g. because of invalid form values, faulty content in Data, an unsupported document language, missing MIP access or a Connect policy.
500 Internal Server Error	Unexpected technical error. The response only contains a generic message and the correlationId.
503 Service Unavailable	A required service is not reachable, e.g. the Identity Server while checking the token (AuthenticationUnavailable), or the server is not set up for the request (Admin.ImportExport.NotConfigured). For AuthenticationUnavailable, retry the call later.

Evaluating errors

• Evaluate the status and code. code is part of the contract and does not change without notice. Base branches in an integration on it, not on title or detail.
• detail is always in English and is not translated according to the language of the caller or the user. The text is addressed to the integrating system and its developers. Use it selectively for display to end users or replace it with your own texts.
• Quote the correlationId to support. The API does not return internal error details such as exception messages or stack traces. They are in the server log under the same identifier.

Error codes

Generic codes say no more than the status and apply when no specific code fits:

Code	Meaning
BadRequest	Invalid request
InvalidBody	The request body could not be read
InvalidQuery	A query or route parameter is missing or invalid
NotFound	Resource not found
Unauthorized	No or invalid access token
AuthenticationUnavailable	The token could not be checked because the Identity Server does not answer
Forbidden	Missing permission
ConcurrentModification	The change collided with a concurrent change (Admin API only)
TechnicalError	Unexpected technical error

Connect API and Connect Session API:

Code	Meaning
Connect.Empty	No Connect in the request
Connect.Invalid	The Connect is invalid, for example not well-formed or without Author
Connect.NotSupported	The Connect requires something the endpoint does not support, e.g. local file paths or desktop commands
Connect.MultipartDocumentMissing	For /Update, the document part is missing from the multipart request
Connect.InvalidConversion	Invalid value for conversion
Connect.UserNotResolved	The user query matches no user or several users
Connect.ExecutionFailed	The Connect could not be executed. detail and errors give the reasons
Connect.SessionNotFound	The session does not exist or has expired
Connect.SessionResultNotFound	No result is stored for the execution
Connect.InvalidSessionTemplate	The Connect Session Template is invalid or not specified
Connect.ConnectedServicesNotReady	The user first has to sign in to connected services

Admin API:

Code	Meaning
Admin.RequiresRole	The caller lacks the required administration role
Admin.RequiresAdminApiClient	The endpoint is only open to Admin API clients and administrators signed in to the Web Admin, not to Connect or MCP tokens
Admin.SecretsRequireInteractiveUser	The operation reveals or replaces secrets and is only open to an administrator signed in to the Web Admin
Admin.InvalidRowVersion	rowVersion is missing or is not a value issued by the server
Admin.Role.Unknown	The route names none of the fixed administration roles
Admin.Role.UnsupportedPrincipalType	Roles can only be assigned to users, directory groups and app user groups
Admin.Role.PrincipalNotFound	The account does not exist in this datasource
Admin.Role.NotMaterialized	The role definition does not exist in this datasource
Admin.Role.DefinitionConflict	Several definitions exist for the role
Admin.Role.MembershipConflict	The role membership was changed concurrently
Admin.DynamicGroup.ConfigurationMissing	The dynamic group has no saved configuration
Admin.DynamicGroup.EvaluationFailed	The saved configuration of the dynamic group cannot be evaluated
Admin.OrganizationUnit.InvalidTheme	The theme of the organisational unit is invalid, e.g. malformed XML
Admin.OrganizationUnit.ThemeRequiresDedicatedEndpoint	Theme fields are written through the theme endpoint, not through the update of the organisational unit
Admin.ImportExport.NotConfigured	No export and import path is configured on the server
Admin.ImportExport.InvalidSelection	The selected objects, dependencies or catalogue nodes are unknown or empty
Admin.ImportExport.MissingPackageFile	The package file is missing
Admin.ImportExport.UnsupportedPackageFormat	The package format is not supported
Admin.ImportExport.PackageTooLarge	The package is too large
Admin.ImportExport.LegacyFile	The export was created with the former DataSourceAdminApp, the file is available there
Admin.ImportExport.ExportNotFinished	The export has not finished yet
Admin.ImportExport.FileNoLongerAvailable	The package file has been removed, a new export is needed
Admin.ImportExport.InvalidDownloadLink	The download link is invalid or has expired
Admin.ImportExport.InvalidChunk	Content-Range, uploadId or the length of the chunk are invalid
Admin.ImportExport.UploadNotFound	The upload does not exist
Admin.ImportExport.UploadInProgress	The upload is still running
Admin.ImportExport.UploadAlreadyCompleted	The upload has already completed
Admin.ImportExport.UploadTotalChanged	The total size of the upload has changed
Admin.ImportExport.UploadChunkOutOfOrder	The chunk does not fit the previous order
Admin.ImportExport.ImportBusy	Another request is currently processing the import. Retry the call later
Admin.ImportExport.InvalidImportState	The import does not allow the requested step in its current state

Without a specific code, 400, 401, 403 and 404 carry the generic code, all 5xx carry TechnicalError and the remaining status codes carry the form Http<Status>, for example Http409 or Http413.

Compatibility

• v2 endpoints keep their previous status codes, except that a server-side cancellation now results in 500 instead of an empty 200. Errors from the shared error handling are also answered with application/problem+json, and InternalMessage is removed from their execution reports. Integrations that previously evaluated message and isError or an empty response body should switch to status, code and detail.
• SCIM endpoints continue to use the error responses of the SCIM standard.
• …/Admin/Fields and …/Admin/Search answer binding errors (invalid JSON body, invalid query value) with the ASP.NET default format ValidationProblemDetails, without code and correlationId.