Get iTwin form data - Forms

Forms

Download API definition:

GET https://api.bentley.com/forms/?iTwinId[&$top][&continuationToken][&type][&state]

Retrieves a list of form data instances for the iTwin with the given ID. If the Prefer header is omitted, or set to "return=minimal", this only returns basic info about each form--its ID, display name, type, and whether it is in an Open, Closed, or Draft state. Setting the Prefer header to "return=representation" will return more data. Use the "Get Form Data Details" endpoint to see full information about a particular form.

Note that the 'iTwinId' query string parameter is required. It must be a valid iTwin or project GUID to get forms from. Old clients can continue to use the 'projectId' parameter as an alias for 'iTwinId'.

Permissions

To use this endpoint, the user is required to have the Forms View permission (Forms_ViewAccess) for the iTwin, or for some forms' definitions if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the View permission as well. If a user does not have permission to view a particular form, it will be silently excluded from the list.)

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

Request parameters

iTwinId

Yes

The GUID of the iTwin or project to get forms for. (Note: projectId is also accepted as an alias for this parameter.)

$top

The number of form data instances to get in each page. Max 50, which is also the default if this parameter is not included.

continuationToken

Parameter that enables continuing to the next page of the previous paged query. This must be passed exactly as it is in the response body's _links.next property. If this is specified and $top is omitted, the next page will be the same size as the previous page.

type

The type of form data to get. Omit to get all types.

state

Set this to only get form data for a particular workflow state (Open, Draft, or Closed).

Request headers

Prefer

Gets whether to return only a summary of each item (return=minimal) or full properties of each item (return=representation).  Default is return=minimal

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

Response

Response 200 OK

json

{
    "formDataInstances": [{
            "id": "00000000-0000-0000-0000-0000000000000",
            "displayName": "Design Meeting 2021-02-07",
            "type": "Meeting Minutes",
            "state": "Closed"
        },
        {
            "id": "00000000-0000-0000-0000-0000000000001",
            "displayName": "Bridge Inspection Safety Checklist",
            "type": "Safety Checklist",
            "state": "Open"
        }
    ],
    "_links": {
        "self": {
            "href": "https://api.bentley.com/forms/?projectId=30273027-1111-2222-3333-3d7d6b02dc46&$top=2"
        },
        "next": {
            "href": "https://api.bentley.com/forms/?projectId=30273027-1111-2222-3333-3d7d6b02dc46&continuationToken=eyJ0b3A999990"
        }
    }
}

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.

json

{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

Response 404 Not Found

This response indicates that the form data instance with the specified ID does not exist or is inaccessible to the user due to insufficient permissions. (For security reasons, the response will not differ between inaccessible and missing forms.)

json

{
    "error": {
        "code": "ProjectNotFound",
        "message": "Requested project is not available.",
        "target": "projectId"
    }
}

Response 422 Unprocessable Entity

This response indicates that there is a problem with the format of the URL. Most likely problem: The 'projectId' parameter is missing or not a valid GUID.

json

{
    "error": {
        "code": "InvalidFormDataRequest",
        "message": "Cannot retrieve form data.",
        "details": [{
            "code": "MissingRequiredParameter",
            "message": "The 'projectId' query parameter must be provided.",
            "target": "projectId"
        }]
    }
}

Response 429 Too many requests

This response indicates that the user has sent too many requests in a given amount of time.

json

{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

Response headers

retry-after

The number of requests exceeds the rate-limit for the client subscription.

Definitions

Form Data List (Prefer return=minimal)

formDataInstances

form-data-summary[]

_links

forward-only-paging-links

json

{
    "type": "object",
    "title": "Form Data List (Prefer return=minimal)",
    "properties": {
        "formDataInstances": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/form-data-summary"
            }
        },
        "_links": {
            "$ref": "#/components/schemas/forward-only-paging-links"
        }
    },
    "additionalProperties": false
}

Form Data List (Prefer return=representation)

formDataInstances

form-data-representation[]

_links

forward-only-paging-links

json

{
    "type": "object",
    "title": "Form Data List (Prefer return=representation)",
    "properties": {
        "formDataInstances": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/form-data-representation"
            }
        },
        "_links": {
            "$ref": "#/components/schemas/forward-only-paging-links"
        }
    },
    "additionalProperties": false
}

Form Data Summary state

Indicates whether the form's current workflow status is an Open, Closed, or Draft status.

Closed

String

Open

String

Draft

String

json

{
    "type": "string",
    "description": "Indicates whether the form's current workflow status is an Open, Closed, or Draft status.",
    "enum": [
        "Closed",
        "Open",
        "Draft"
    ],
    "title": "Form Data Summary state"
}

Form Data Summary

String

The form data instance's unique ID. Can be used to query for all of its properties using the 'Get form data details' endpoint.

displayName

String, null

Name that should be used to display this form to users.

type

String

Read-only. Describes which domain of work the form involves, which determines what applications will show it. This is automatically set based on the associated form definition referenced by the formId property.

Form Data Summary state

form-data-summary-state

Indicates whether the form's current workflow status is an Open, Closed, or Draft status.

json

{
    "type": "object",
    "title": "Form Data Summary",
    "properties": {
        "id": {
            "type": "string",
            "description": "The form data instance's unique ID. Can be used to query for all of its properties using the 'Get form data details' endpoint."
        },
        "displayName": {
            "type": "string",
            "nullable": true,
            "description": "Name that should be used to display this form to users."
        },
        "type": {
            "type": "string",
            "description": "Read-only. Describes which domain of work the form involves, which determines what applications will show it. This is automatically set based on the associated form definition referenced by the `formId` property."
        },
        "state": {
            "type": "string",
            "description": "Indicates whether the form's current workflow status is an Open, Closed, or Draft status.",
            "enum": [
                "Closed",
                "Open",
                "Draft"
            ],
            "title": "Form Data Summary state",
            "$ref": "#/components/schemas/form-data-summary-state"
        }
    },
    "additionalProperties": false
}

Form Data Representation

Contains the full data of this form, except for formId, for inclusion in a list. Any property that was never set on the form will be omitted from the response.

String

Unique identifier for this instance. Read-only.

displayName

String, null

Name that should be used to show this form in a list of form data instances in the UI. This is read-only. Project managers can configure how this is generated; usually, it will be the value of another property.

subject

String, null

Brief title/description of the form.

description

String, null

Detailed description of the form.

type

String

number

String, null

An human-readable identifier for the form, consisting of an alphanumeric prefix (that can be configured by the project administrator) followed by an auto-incrementing number. Read-only.

dueDate

Date-time, null

The date by which an action should be taken on this form. Applications will use this to determine whether a form is near due or overdue.

status

String

The current workflow status the form is in right now.

state

String

Indicates whether the form's status is an Open, Closed, or Draft status. This property is read-only.

statusColor

String, null

A RBG hexadecimal color string, e.g. #ff0000. Read-only. If set, this gives a hint for how to highlight the form in a list of forms based on its current workflow status.

assignee

primary-assignee

The primary user or role assigned to this form.

assignees

secondary-assignee[]

For cases when a form is assigned to multiple people and/or roles, this lists all of them rather than just the primary assignee.

createdBy

String

The display name of the user who originally created this form data instance. Read-only.

createdDateTime

String

The date and time when this form data instance was originally created. Read-only.

lastModifiedBy

String

The display name of the user who most recently made a change to this form data instance. Read-only.

lastModifiedDateTime

String

The date and time when this form data instance was most recently edited. Read-only.

sourceEntity

One of: source-entity-file source-entity-i-model-element

Origin info. An object linking the form to an entity outside the Forms service, such as a file in Storage or an element in an iModel, that the form was created to pertain to.

boundingBox

bounding-box

Origin info. Describes a rectangular-prism area of the model that the form pertains to.

modelPin

model-pin

Origin info. Describes a point in 3D space that the form pertains to. May or may not be based on the position of a particular element.

modelView

model-view

Origin info. Describes a view of the model that shows the relevant elements that the form pertains to.

modelEventDateTime

Date-time, null

The date and time represented in the model where the form pertains (if in a 4D model).

location

properties

dynamic-object

Contains all form-type-specific and user-defined properties that were set on this form. Properties set here may be strings, numbers, booleans, arrays, or objects, depending on how the project's administrator defined them in the Form Designer.

_links

One of: source-entity-links-file source-entity-links-i-model-element

Links to related entities, if applicable.

json

{
    "type": "object",
    "title": "Form Data Representation",
    "description": "Contains the full data of this form, except for formId, for inclusion in a list. Any property that was never set on the form will be omitted from the response.",
    "properties": {
        "id": {
            "type": "string",
            "description": "Unique identifier for this instance. Read-only."
        },
        "displayName": {
            "type": "string",
            "nullable": true,
            "description": "Name that should be used to show this form in a list of form data instances in the UI. This is read-only. Project managers can configure how this is generated; usually, it will be the value of another property."
        },
        "subject": {
            "type": "string",
            "nullable": true,
            "description": "Brief title/description of the form."
        },
        "description": {
            "type": "string",
            "nullable": true,
            "description": "Detailed description of the form."
        },
        "type": {
            "type": "string",
            "description": "Read-only. Describes which domain of work the form involves, which determines what applications will show it. This is automatically set based on the associated form definition referenced by the `formId` property."
        },
        "number": {
            "type": "string",
            "nullable": true,
            "description": "An human-readable identifier for the form, consisting of an alphanumeric prefix (that can be configured by the project administrator) followed by an auto-incrementing number. Read-only."
        },
        "dueDate": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "The date by which an action should be taken on this form. Applications will use this to determine whether a form is near due or overdue."
        },
        "status": {
            "type": "string",
            "description": "The current workflow status the form is in right now."
        },
        "state": {
            "type": "string",
            "description": "Indicates whether the form's status is an Open, Closed, or Draft status. This property is read-only."
        },
        "statusColor": {
            "type": "string",
            "nullable": true,
            "description": "A RBG hexadecimal color string, e.g. `#ff0000`. Read-only. If set, this gives a hint for how to highlight the form in a list of forms based on its current workflow status."
        },
        "assignee": {
            "description": "The primary user or role assigned to this form.",
            "$ref": "#/components/schemas/primary-assignee"
        },
        "assignees": {
            "type": "array",
            "description": "For cases when a form is assigned to multiple people and/or roles, this lists all of them rather than just the primary assignee.",
            "items": {
                "$ref": "#/components/schemas/secondary-assignee"
            }
        },
        "createdBy": {
            "type": "string",
            "description": "The display name of the user who originally created this form data instance. Read-only."
        },
        "createdDateTime": {
            "type": "string",
            "description": "The date and time when this form data instance was originally created. Read-only."
        },
        "lastModifiedBy": {
            "type": "string",
            "description": "The display name of the user who most recently made a change to this form data instance. Read-only."
        },
        "lastModifiedDateTime": {
            "type": "string",
            "description": "The date and time when this form data instance was most recently edited. Read-only."
        },
        "sourceEntity": {
            "description": "Origin info. An object linking the form to an entity outside the Forms service, such as a file in Storage or an element in an iModel, that the form was created to pertain to.",
            "oneOf": [
                {
                    "$ref": "#/components/schemas/source-entity-file"
                },
                {
                    "$ref": "#/components/schemas/source-entity-i-model-element"
                }
            ]
        },
        "boundingBox": {
            "description": "Origin info. Describes a rectangular-prism area of the model that the form pertains to.",
            "$ref": "#/components/schemas/bounding-box"
        },
        "modelPin": {
            "description": "Origin info. Describes a point in 3D space that the form pertains to. May or may not be based on the position of a particular element.",
            "$ref": "#/components/schemas/model-pin"
        },
        "modelView": {
            "description": "Origin info. Describes a view of the model that shows the relevant elements that the form pertains to.",
            "$ref": "#/components/schemas/model-view"
        },
        "modelEventDateTime": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "The date and time represented in the model where the form pertains (if in a 4D model)."
        },
        "location": {
            "$ref": "#/components/schemas/location"
        },
        "properties": {
            "description": "Contains all form-type-specific and user-defined properties that were set on this form.  Properties set here may be strings, numbers, booleans, arrays, or objects, depending on how the project's administrator defined them in the Form Designer.",
            "$ref": "#/components/schemas/dynamic-object"
        },
        "_links": {
            "description": "Links to related entities, if applicable.",
            "oneOf": [
                {
                    "$ref": "#/components/schemas/source-entity-links-file"
                },
                {
                    "$ref": "#/components/schemas/source-entity-links-i-model-element"
                }
            ]
        }
    },
    "additionalProperties": false
}

Primary Assignee

An object describing the primary user or role assigned to a form.

String

The GUID identifying the user or role.

displayName

String

The role's name, or the user's given name and surname, as it should be displayed in an application.

json

{
    "type": "object",
    "nullable": true,
    "title": "Primary Assignee",
    "description": "An object describing the primary user or role assigned to a form.",
    "properties": {
        "id": {
            "type": "string",
            "description": "The GUID identifying the user or role."
        },
        "displayName": {
            "type": "string",
            "description": "The role's name, or the user's given name and surname, as it should be displayed in an application."
        }
    },
    "additionalProperties": false
}

Secondary Assignee

An object describing one of potentially several users or roles assigned to a form.

String

The GUID identifying the user or role.

displayName

String

The role's name, or the user's given name and surname, as it should be displayed in an application.

isRole

Boolean

If true, this is a role; otherwise, it is an individual user.

json

{
    "type": "object",
    "title": "Secondary Assignee",
    "description": "An object describing one of potentially several users or roles assigned to a form.",
    "properties": {
        "id": {
            "type": "string",
            "description": "The GUID identifying the user or role."
        },
        "displayName": {
            "type": "string",
            "description": "The role's name, or the user's given name and surname, as it should be displayed in an application."
        },
        "isRole": {
            "type": "boolean",
            "description": "If true, this is a role; otherwise, it is an individual user."
        }
    },
    "additionalProperties": false
}

Bounding Box

Origin info. Describes a rectangular-prism-shaped region in a 3D model that the form pertains to.

lowerLeftPoint3D

point3D

The lower-left corner of the region.

upperRightPoint3D

point3D

The upper-right corner of the region.

json

{
    "type": "object",
    "nullable": true,
    "title": "Bounding Box",
    "description": "Origin info. Describes a rectangular-prism-shaped region in a 3D model that the form pertains to.",
    "properties": {
        "lowerLeftPoint3D": {
            "description": "The lower-left corner of the region.",
            "$ref": "#/components/schemas/point3D"
        },
        "upperRightPoint3D": {
            "description": "The upper-right corner of the region.",
            "$ref": "#/components/schemas/point3D"
        }
    },
    "additionalProperties": false
}

model-pin

Origin info. Associates a form with a single point in a model that does not necessarily correspond to a model element.

location

point3D

The location of the pin.

description

String, null

String describing the relevance of the pin's location.

json

{
    "type": "object",
    "nullable": true,
    "description": "Origin info. Associates a form with a single point in a model that does not necessarily correspond to a model element.",
    "properties": {
        "location": {
            "description": "The location of the pin.",
            "$ref": "#/components/schemas/point3D"
        },
        "description": {
            "type": "string",
            "nullable": true,
            "description": "String describing the relevance of the pin's location."
        }
    },
    "additionalProperties": false
}

Model View

Origin info. Describes the view that was visible when the form was created.

cameraView

camera

An object describing the view that can be parsed by non-IModelJS applications.

iModelJsView

String, null

The ID of a saved view showing a location relevant to the form.

json

{
    "type": "object",
    "nullable": true,
    "title": "Model View",
    "description": "Origin info. Describes the view that was visible when the form was created.",
    "properties": {
        "cameraView": {
            "description": "An object describing the view that can be parsed by non-IModelJS applications.",
            "$ref": "#/components/schemas/camera"
        },
        "iModelJsView": {
            "type": "string",
            "nullable": true,
            "description": "The ID of a saved view showing a location relevant to the form."
        }
    },
    "additionalProperties": false
}

point3D

Number

json

{
    "type": "object",
    "nullable": true,
    "properties": {
        "x": {
            "type": "number"
        },
        "y": {
            "type": "number"
        },
        "z": {
            "type": "number"
        }
    },
    "additionalProperties": false
}

camera

viewPoint

point3D

The location of the camera within the model.

direction

point3D

Endpoint of a vector from the origin that determines the camera's facing direction.

point3D

Endpoint of a vector from the origin that determines which direction appears as upwards in the view.

viewToWorldScale

Number, null

Determines the zoom level of the camera, i.e. how much to multiply 1 distance unit in the view by to get the actual distance in meters in the model. Either this or fieldOfView should be specified, but not both.

fieldOfView

Number, null

Determines the number of degrees in the circular arc around the camera's position that is visible in the view. Either this or viewToWorldScale should be specified, but not both.

json

{
    "type": "object",
    "nullable": true,
    "properties": {
        "viewPoint": {
            "$ref": "#/components/schemas/point3D",
            "description": "The location of the camera within the model."
        },
        "direction": {
            "$ref": "#/components/schemas/point3D",
            "description": "Endpoint of a vector from the origin that determines the camera's facing direction."
        },
        "up": {
            "$ref": "#/components/schemas/point3D",
            "description": "Endpoint of a vector from the origin that determines which direction appears as upwards in the view."
        },
        "viewToWorldScale": {
            "type": "number",
            "nullable": true,
            "description": "Determines the zoom level of the camera, i.e. how much to multiply 1 distance unit in the view by to get the actual distance in meters in the model. Either this or fieldOfView should be specified, but not both."
        },
        "fieldOfView": {
            "type": "number",
            "nullable": true,
            "description": "Determines the number of degrees in the circular arc around the camera's position that is visible in the view. Either this or viewToWorldScale should be specified, but not both."
        }
    },
    "additionalProperties": false
}

location

Origin info. The geographical location the form pertains to.

latitude

Number, null

The degrees latitude of the form's location. North: positive, south: negative.

longitude

Number, null

The degrees longitude of the form's location. East: positive, west: negative.

elevation

Number, null

The geographical elevation above/below sea level. Units for this property are not standardized, so an application should not make assumptions about this property's value set by other applications unless that other application's units are known.

description

String, null

A string describing the significance of this location.

json

{
    "type": "object",
    "nullable": true,
    "description": "Origin info. The geographical location the form pertains to.",
    "properties": {
        "latitude": {
            "type": "number",
            "nullable": true,
            "description": "The degrees latitude of the form's location. North: positive, south: negative."
        },
        "longitude": {
            "type": "number",
            "nullable": true,
            "description": "The degrees longitude of the form's location. East: positive, west: negative."
        },
        "elevation": {
            "type": "number",
            "nullable": true,
            "description": "The geographical elevation above/below sea level. Units for this property are not standardized, so an application should not make assumptions about this property's value set by other applications unless that other application's units are known."
        },
        "description": {
            "type": "string",
            "nullable": true,
            "description": "A string describing the significance of this location."
        }
    },
    "additionalProperties": false
}

source-entity-file

Represents a file in Storage about which a form was created.

storageFile.fileId

String

ID used to identify the file in the Storage API.

storageFile.folderId

String

ID of the folder containing the file in the Storage API.

storageFile.fileName

String, null

Name of the file, including extension.

json

{
    "type": "object",
    "nullable": true,
    "description": "Represents a file in Storage about which a form was created.",
    "properties": {
        "storageFile": {
            "type": "object",
            "nullable": true,
            "description": "The info about the file.",
            "properties": {
                "fileId": {
                    "type": "string",
                    "description": "ID used to identify the file in the Storage API."
                },
                "folderId": {
                    "type": "string",
                    "description": "ID of the folder containing the file in the Storage API."
                },
                "fileName": {
                    "type": "string",
                    "nullable": true,
                    "description": "Name of the file, including extension."
                }
            },
            "required": [
                "fileId",
                "folderId"
            ],
            "additionalProperties": false
        }
    },
    "required": [
        "storageFile"
    ],
    "additionalProperties": false
}

source-entity-i-model-element

Represents an element in an iModel about which a form was created.

iModelElement.modelId

String

ID of the iModel containing the element, as it exists in the iModels API.

iModelElement.elementId

String

ID of the element. Can be a hexadecimal numeric string (space-separated to include multiple elements) or a presentation key.

iModelElement.changeSetId

String

ID of the changeset where the form was created.

iModelElement.modelName

String

Name of the model.

json

{
    "type": "object",
    "nullable": true,
    "description": "Represents an element in an iModel about which a form was created.",
    "properties": {
        "iModelElement": {
            "type": "object",
            "nullable": true,
            "description": "The info about the element.",
            "properties": {
                "modelId": {
                    "type": "string",
                    "description": "ID of the iModel containing the element, as it exists in the iModels API."
                },
                "elementId": {
                    "type": "string",
                    "description": "ID of the element. Can be a hexadecimal numeric string (space-separated to include multiple elements) or a presentation key."
                },
                "changeSetId": {
                    "type": "string",
                    "description": "ID of the changeset where the form was created."
                },
                "modelName": {
                    "type": "string",
                    "description": "Name of the model."
                }
            },
            "required": [
                "modelId",
                "elementId",
                "changeSetId",
                "modelName"
            ],
            "additionalProperties": false
        }
    },
    "required": [
        "iModelElement"
    ],
    "additionalProperties": false
}

source-entity-links-file

Links to retrieve the related file, and the folder that contains it, from the Storage API.

folder

link

file

link

json

{
    "type": "object",
    "description": "Links to retrieve the related file, and the folder that contains it, from the Storage API.",
    "properties": {
        "folder": {
            "$ref": "#/components/schemas/link"
        },
        "file": {
            "$ref": "#/components/schemas/link"
        }
    },
    "required": [
        "folder",
        "file"
    ],
    "additionalProperties": false
}

source-entity-links-i-model-element

Links to retrieve the related element's specific changeset, or iModel in general, from the iModels API.

iModel

link

iModelChangeset

link

json

{
    "type": "object",
    "nullable": true,
    "description": "Links to retrieve the related element's specific changeset, or iModel in general, from the iModels API.",
    "properties": {
        "iModel": {
            "$ref": "#/components/schemas/link"
        },
        "iModelChangeset": {
            "$ref": "#/components/schemas/link"
        }
    },
    "required": [
        "iModel",
        "iModelChangeset"
    ],
    "additionalProperties": false
}

Dynamic Object

An object whose properties can vary depending on user customization within the project.

Forward Only Paging Links

URLs for redoing the current request or getting the next page of results, if applicable. Links to the previous page are not available.

self

link

json

{
    "type": "object",
    "title": "Forward Only Paging Links",
    "description": "URLs for redoing the current request or getting the next page of results, if applicable. Links to the previous page are not available.",
    "properties": {
        "self": {
            "$ref": "#/components/schemas/link"
        },
        "next": {
            "$ref": "#/components/schemas/link"
        }
    },
    "additionalProperties": false
}

link

href

String

json

{
    "type": "object",
    "properties": {
        "href": {
            "type": "string"
        }
    },
    "additionalProperties": false
}

DetailedError

Contains error information and an array of more specific errors.

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String, null

The target of the error.

details

Error[]

Optional array of more specific errors.

json

{
    "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.

error

DetailedError

Error Detailed information.

json

{
    "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.

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String, null

The target of the error.

json

{
    "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

error

Error

Error information.

json

{
    "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?