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. In case of an error, the following HTTP status codes are used:
| Status | Meaning |
|---|---|
400 Bad Request | Invalid input, e.g. malformed Connect XML or invalid parameters. |
401 Unauthorized | No or invalid access token. |
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 or an expired session. |
500 Internal Server Error | Unexpected error during processing. |
Unhandled errors are returned as JSON in the following format:
{
"message": "Description of the error",
"isError": true,
"detail": "Additional details (including stack trace only in debug builds)"
}
The Web API generally does not use RFC 7807 (ProblemDetails). Exceptions are individual areas of the Admin API, among them the package export and import and the themes of organisational units: they respond to functional errors with ProblemDetails and a machine-readable code. Individual Connect API endpoints may additionally return a domain-specific report (ConnectResultReport, see Connect API) in case of an error.