Requests that anywhere from 1 to 5 issues be exported to a file and saved in cloud-based storage (accessible through the Storage API). Currently 'pdf' is the only supported file type. The IDs of the issues must be specified in a query string parameter named "ids", separated by commas if there is more than one. A sample request URL that exports 3 issues to a PDF is as follows--
Note that unlike most GET requests, this is not an idempotent operation; each time it is called, a new file will be generated. The response will not contain the file itself, but links to download it from Storage.
All issues specified in the request must come from the same iTwin, or the request will fail. The client may also specify the ID of a destination folder where the file should be saved; otherwise, it will be saved in the iTwin's root folder. They can also specify whether to include a textual header with issue metadata at the top of each page (default) or exclude it.
Authentication
Requires Authorization
header with valid Bearer token for scope itwin-platform
.
For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.
Request parameters
Instance IDs of issues to export. Must include at least 1, but no more than 5, IDs, separated by commas, and they all must come from the same project.
If exporting to PDF, indicates whether to include metadata on top of each page. Default is true.
Indicates the type of file to create. Right now PDF is the only valid option, and is the default if not specified.
The ID, as retrieved from the Storage API, of the folder where the produced file should be saved. If not set, will default to the project's root folder.
Request headers
OAuth access token with itwin-platform
scope
Setting to application/vnd.bentley.itwin-platform.v1+json
is recommended.
Response 200 OK
Indicates that the file was generated successfully. The response includes the generated file's filename as well as links for using the Storage API to retrieve it.
{ "file": { "fileName": "Generated_20220313_1234554321", "_links": { "destinationFolder": { "href": "https://api.bentley.com/storage/folders/ab12cd34ef56gh78" }, "fileMetadata": { "href": "https://api.bentley.com/storage/files/zy09xw87vu65ts43" }, "fileDownload": { "href": "https://api.bentley.com/storage/files/zy09xw87vu65ts43/download" } } } }
Response 401 Unauthorized
This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.
{ "error": { "code": "HeaderNotFound", "message": "Header Authorization was not found in the request. Access denied." } }
Response 404 Not Found
Either one of the issues specified does not exist (code = 'IssueNotFound') or the destination folder does not exist (code = 'FolderNotFound').
{ "error": { "code": "FolderNotFound", "message": "Requested folder is not available.", "target": "folderId" } }
Response 422 Unprocessable Entity
This response indicates that there is a problem with the request parameters. Depending on the problem, the 'details' array may include specific errors.
{ "error": { "code": "InvalidExportRequest", "message": "One or more parameters in the query string are invalid. See 'details' property for specifics.", "details": [{ "code": "InvalidValue", "message": "The 'includeHeader' property is of an incorrect type. Expected boolean.", "target": "includeHeader" }, { "code": "InvalidValue", "message": "The IDs 'a' and 'b' come from different projects. All items included together in a PDF must come from the same project.", "target": "ids" }, { "code": "InvalidValue", "message": "The 'folderId' parameter is not a valid ID.", "target": "folderId" } ] } }
Response 429 Too many requests
This response indicates that the user has sent too many requests in a given amount of time.
{ "error": { "code": "TooManyRequests", "message": "More requests were received than the subscription rate-limit allows." } }
Response headers
The number of requests exceeds the rate-limit for the client subscription.
Export Issues to Storage (response)
{ "type": "object", "title": "Export Issues to Storage (response)", "properties": { "file": { "$ref": "#/components/schemas/export-issues-to-storage-response-entity" } }, "additionalProperties": false }
Export Issues to Storage (response) Entity
The name of the exported file. (If multiple files were generated for this request, each beyond the first will start with the same name, but with a number in parentheses added just before the file extension.)
{ "type": "object", "title": "Export Issues to Storage (response) Entity", "properties": { "fileName": { "type": "string", "description": "The name of the exported file. (If multiple files were generated for this request, each beyond the first will start with the same name, but with a number in parentheses added just before the file extension.)" }, "_links": { "$ref": "#/components/schemas/export-file-to-share-links" } }, "additionalProperties": false }
Export File to Share Links
Links to view the folder where the file was placed, view the file metadata, or download the file contents. The fileMetadata link can also be used to delete the file.
{ "type": "object", "title": "Export File to Share Links", "description": "Links to view the folder where the file was placed, view the file metadata, or download the file contents. The fileMetadata link can also be used to delete the file.", "properties": { "fileDownload": { "$ref": "#/components/schemas/link" }, "destinationFolder": { "$ref": "#/components/schemas/link" }, "fileMetadata": { "$ref": "#/components/schemas/link" } }, "additionalProperties": false }
link
{ "type": "object", "properties": { "href": { "type": "string" } }, "additionalProperties": false }
DetailedError
Contains error information and an array of more specific errors.
One of a server-defined set of error codes.
A human-readable representation of the error.
The target of the error.
{ "type": "object", "description": "Contains error information and an array of more specific errors.", "properties": { "code": { "type": "string", "description": "One of a server-defined set of error codes." }, "message": { "type": "string", "description": "A human-readable representation of the error." }, "target": { "type": "string", "description": "The target of the error.", "nullable": true }, "details": { "type": "array", "description": "Optional array of more specific errors.", "items": { "$ref": "#/components/schemas/Error" } } }, "required": [ "code", "message", "details" ], "additionalProperties": true }
Detailed Error Response
Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.
{ "type": "object", "title": "Detailed Error Response", "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.", "properties": { "error": { "description": "Error Detailed information.", "$ref": "#/components/schemas/DetailedError" } }, "required": [ "error" ], "additionalProperties": false }
Error
Contains error information.
One of a server-defined set of error codes.
A human-readable representation of the error.
The target of the error.
{ "type": "object", "description": "Contains error information.", "properties": { "code": { "type": "string", "description": "One of a server-defined set of error codes." }, "message": { "type": "string", "description": "A human-readable representation of the error." }, "target": { "type": "string", "description": "The target of the error.", "nullable": true } }, "required": [ "code", "message" ], "additionalProperties": true }
Error Response
Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.
{ "type": "object", "title": "Error Response", "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.", "properties": { "error": { "description": "Error information.", "$ref": "#/components/schemas/Error" } }, "required": [ "error" ], "additionalProperties": false }
Was this page helpful?