openapi: 3.0.0 info: title: Vault description: > The Vault API manages secure content files and document storage for other Apiture APIs and application use. Documents which may be stored in Vault include _Terms and Conditions_, privacy statements, check images, statements, images/documents required for an account application, etc. Clients may upload and download files with this API, or search for files by date or type or role. Files may be organized into hierarchical folders. Each file has a JSON representation _file descriptor_ which includes the attributes (metadata) of the file (the name, type, size, `_links`, etc.), and a `content` resource which accesses the text or binary content of the file. The content URI is available via the *`apiture:content`* link in the file descriptor. The `_links` of a file or folder include an *`apiture:folder`* link to its containing folder. Each folder has *`apiture:files`* and *`apiture:children`* links to its directly contained files and subfolders, respectively. To upload a file, first `POST` a request to the `/uploads` path (the `createUpload` operation) containing file descriptor(s) to be uploaded. When uploading a new file, the caller may specify a desired target folder by setting the *`apiture:folder`* link within the request's `_links`. The _upload tracker response_ from the upload operation contains an array of items, one for each file to upload. Each item in the array contains an *`apiture:uploadUrl`* link, which is an upload URL for the corresponding file. The client should next `PUT` the file(s) content to the upload URLs to upload the files' contents. The upload is done when the upload resource `state` is `completed` or `failed`. The upload resource will contain the file descriptor resources in the `items` array within the `_embedded` object; each file will include a `self` link to the corresponding file resource. After a file has been created, the file resource contains links to its containing folder, the public share URI, and the content URI for downloading the file's content. For files which reside in folders with revisions enabled, updating a file's content creates a new revision of the file. The revisions are available from the file's `/files/{fileId}/revisions` collection. # Error Types Error responses in this API may have one of the `type` values described below. See [Errors](https://developer.apiture.com/docs/concepts/errors) for more information on error responses and error types.

createStorageFolderFailed

**Description**: Error occurred while trying to create AWS S3 folder.
**Remediation**: Check to make sure that the supplied bucket and folderName are valid and resolve any errors in _error.

fileInvalidCategory

**Description**: Category is invalid.
**Remediation**: Check to make sure that category corresponds to an enum value.

fileInvalidType

**Description**: File type is invalid.
**Remediation**: Check to make sure the file type matches the specified content type.

folderMissingName

**Description**: Name is missing.
**Remediation**: Check to make sure that name exists.

invalidFileId

**Description**: No Files were found for the specified fileId.
**Remediation**: Check to make sure that the supplied fileId corresponds to an apiture file resource.

invalidFilesFilter

**Description**: No Files were found with the specified filter.
**Remediation**: Check to make sure that the supplied filter corresponds to an apiture file resource.

invalidFolderId

**Description**: No Folders were found for the specified folderId.
**Remediation**: Check to make sure that the supplied folderId corresponds to an apiture folder resource.

invalidUploadId

**Description**: No Uploads were found for the specified uploadId.
**Remediation**: Check to make sure that the supplied uploadId corresponds to an apiture upload resource.

malformedRequestBody

**Description**: The supplied request body was malformed.
**Remediation**: Check to make sure that your request body exists and that it does not contain syntax errors.

notEmptyFolder

**Description**: There are files in the folder.
**Remediation**: Remove files from the folder. version: 0.11.0 contact: name: Apiture url: 'https://developer.apiture.com' email: api@apiture.com termsOfService: 'https://developer.apiture.com/docs/Apiture-Open-API-License-Agreement.pdf' license: name: Pending. tags: - name: API description: Endpoints which describe this API. - name: Upload description: Requests to upload new files into the file vault. - name: File description: A file (document) in the file vault. - name: Folder description: A container for files and other folders. paths: /folders: get: summary: Return a collection of folders description: >- Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting) [filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searchable) collection of folders. The [links](https://developer.apiture.com/docs/concepts/links) in the response include pagination links. operationId: getFolders security: - apiKey: [] accessToken: - data/read x-apiture-implemented: true tags: - Folder x-apiture-traits: sortBy: - name itemSchema: folder filters: name: filter: - eq - ne - lt - le - gt - ge - startsWith - endsWith - contains - search _id: filter: - eq - in parameters: - name: start in: query description: 'The zero-based index of the first folder in this page. The default, 0, represents the first page of the collection.' schema: type: integer format: int64 default: 0 - name: limit in: query description: The maximum number of folder representations to return in this page. schema: type: integer format: int32 default: 100 - name: sortBy in: query description: >- Optional sort criteria. See [sort criteria format](https://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.
This collection may be sorted by following properties:
• `name` schema: type: string - name: name in: query description: >- Subset the folders collection to those with this name value. Use `|` to separate multiple values. For example, `?name=Bartell` matches only items whose name is Bartell; `?name=Bartell|kirsten` matches items whose name is Bartell or kirsten. This is combined with an implicit and with other filters if they are used. See [filtering](https://developer.apiture.com/docs/concepts/filtering). schema: type: string - name: filter in: query description: >- Optional filter criteria. See [filtering](https://developer.apiture.com/docs/concepts/filtering).
This collection may be filtered by following properties and functions:
• Property `name` using functions `eq`, `ne`, `lt`, `le`, `gt`, `ge`, `startsWith`, `endsWith`, `contains`, `search`
• Property `_id` using functions `eq`, `in` schema: type: string - $ref: '#/components/parameters/qQueryParam' - $ref: '#/components/parameters/folderQueryParam' responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/folders' application/json: schema: $ref: '#/components/schemas/folders' '400': $ref: '#/components/responses/400' '422': $ref: '#/components/responses/422' post: summary: Create a new folder description: >- Create a new folder in the folders collection. To locate the folder within an existing folder (as a subfolder), specify the desired target folder with the *`apiture:folder`* link within the request body's `_links`. operationId: createFolder security: - apiKey: [] accessToken: - data/write x-apiture-implemented: true tags: - Folder requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/createFolder' application/json: schema: $ref: '#/components/schemas/createFolder' description: The data necessary to create a new folder. required: true responses: '201': description: Created headers: Location: description: >- The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with *`scheme`*`://host`. schema: type: string format: uri ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/folder' application/json: schema: $ref: '#/components/schemas/folder' '400': description: >- Bad Request. The request body or one or more of the query parameters was not well formed. The `_error` field in the response will contain details about the request error. This error response may have one of the following `type` values: * [`malformedRequestBody`](#err-malformedRequestBody) * [`folderMissingName`](#err-folderMissingName) * [`createStorageFolderFailed`](#err-createStorageFolderFailed) x-apiture-errors: - malformedRequestBody - folderMissingName - createStorageFolderFailed parameters: [] '/folders/{folderId}': get: summary: Fetch a representation of this folder description: 'Return a [HAL](https://developer.apiture.com/docs/concepts/hal) representation of this folder resource.' operationId: getFolder security: - apiKey: [] accessToken: - data/read x-apiture-implemented: true tags: - Folder parameters: - $ref: '#/components/parameters/folderIdPathParam' - $ref: '#/components/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this folder resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/folder' application/json: schema: $ref: '#/components/schemas/folder' '304': $ref: '#/components/responses/304' '404': $ref: '#/components/responses/404Folder' put: summary: Update this folder description: Perform a complete replacement of this folder. operationId: updateFolder security: - apiKey: [] accessToken: - data/write x-apiture-implemented: true tags: - Folder parameters: - $ref: '#/components/parameters/folderIdPathParam' - $ref: '#/components/parameters/ifMatchHeaderParam' requestBody: $ref: '#/components/requestBodies/folder' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this folder resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/folder' application/json: schema: $ref: '#/components/schemas/folder' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404Folder' '412': $ref: '#/components/responses/412' '422': $ref: '#/components/responses/422' patch: summary: Update this folder description: Perform a partial update of this folder. Fields which are omitted are not updated. Nested `_embedded` and `_links` are ignored if included. operationId: patchFolder security: - apiKey: [] accessToken: - data/write x-apiture-implemented: true tags: - Folder parameters: - $ref: '#/components/parameters/folderIdPathParam' - $ref: '#/components/parameters/ifMatchHeaderParam' requestBody: $ref: '#/components/requestBodies/folder' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this folder resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/folder' application/json: schema: $ref: '#/components/schemas/folder' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404Folder' '412': $ref: '#/components/responses/412' '422': $ref: '#/components/responses/422' delete: summary: Delete this folder resource description: >- Delete this folder.

Normally, one can only delete a folder if it is empty (contains no files or subfolders). With the `?recursive=true` option, this operation will delete a non-empty folder and its contents, including nested folders. The user must have authorization to delete all the contents.

The user may not delete their top-level folder. operationId: deleteFolder security: - apiKey: [] accessToken: - data/delete x-apiture-implemented: true tags: - Folder parameters: - $ref: '#/components/parameters/ifMatchHeaderParam' - $ref: '#/components/parameters/folderIdPathParam' - name: recursive in: query description: 'If true, also delete all files and nested folders that are stored in this folder.' schema: type: boolean default: false responses: '204': $ref: '#/components/responses/204Deleted' '404': $ref: '#/components/responses/404Folder' '409': $ref: '#/components/responses/409Folder' '412': $ref: '#/components/responses/412' /files: get: summary: Return a collection of files description: >- Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting) [filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searchable) collection of files. The [links](https://developer.apiture.com/docs/concepts/links) in the response include pagination links. operationId: getFiles security: - apiKey: [] accessToken: - data/read x-apiture-implemented: true tags: - File x-apiture-traits: sortBy: - type - name itemSchema: file filters: type: filter: - eq - ne - in name: filter: - eq - ne - lt - le - gt - ge - startsWith - endsWith - contains - search _id: filter: - eq - in parameters: - name: start in: query description: 'The zero-based index of the first file in this page. The default, 0, represents the first page of the collection.' schema: type: integer format: int64 default: 0 - name: limit in: query description: The maximum number of file representations to return in this page. schema: type: integer format: int32 default: 100 - name: sortBy in: query description: >- Optional sort criteria. See [sort criteria format](https://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.
This collection may be sorted by following properties:
• `type`
• `name` schema: type: string - name: name in: query description: >- Subset the files collection to those with this name value. Use `|` to separate multiple values. For example, `?name=Bartell` matches only items whose name is Bartell; `?name=Bartell|kirsten` matches items whose name is Bartell or kirsten. This is combined with an implicit and with other filters if they are used. See [filtering](https://developer.apiture.com/docs/concepts/filtering). schema: type: string - $ref: '#/components/parameters/typeQueryParam' - name: filter in: query description: >- Optional filter criteria. See [filtering](https://developer.apiture.com/docs/concepts/filtering).
This collection may be filtered by following properties and functions:
• Property `type` using functions `eq`, `ne`, `in`
• Property `name` using functions `eq`, `ne`, `lt`, `le`, `gt`, `ge`, `startsWith`, `endsWith`, `contains`, `search`
• Property `_id` using functions `eq`, `in` schema: type: string - $ref: '#/components/parameters/qQueryParam' - $ref: '#/components/parameters/folderQueryParam' responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/files' application/json: schema: $ref: '#/components/schemas/files' '400': $ref: '#/components/responses/400' '422': $ref: '#/components/responses/422' post: summary: Create a new file description: >- Create a new file in the files collection. This operation is called upon successful completion of an upload operation and associates the file descriptor (name, description, parent folder, etc.) with the file contents.

If there is already a file of the same name in the target folder, the file is renamed by adding a unique numeric suffix in parentheses. For example, if `tax-summary-2018.pdf` already exists, uploading a new document with that name will be renamed `tax-summary-2018 (1).pdf`.

The file will be placed in the folder specified in the *`apiture:folder`* link, which should be derived from the *`apiture:folder`* specified in upload request. If no folder was specified, the file is placed in the user's uploads folder. operationId: createFile security: - apiKey: [] accessToken: - data/write x-apiture-implemented: true tags: - File requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/createFile' application/json: schema: $ref: '#/components/schemas/createFile' description: The data necessary to create a new file. required: true responses: '201': description: Created headers: Location: description: >- The URI of the new resource. If the URI begins with `/` it is relative to the API root context. Else, it is a full URI starting with *`scheme`*`://host` schema: type: string format: uri ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/file' application/json: schema: $ref: '#/components/schemas/file' '400': $ref: '#/components/responses/400CreateFile' parameters: [] '/files/{fileId}': get: summary: Fetch the file descriptor description: >- Return a [HAL](https://developer.apiture.com/docs/concepts/hal) representation of this file resource. The `Content-Location` response header, if present, identifies the equivalent revision. operationId: getFile security: - apiKey: [] accessToken: - data/read x-apiture-implemented: true tags: - File parameters: - $ref: '#/components/parameters/fileIdPathParam' - $ref: '#/components/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this file resource. schema: type: string Content-Location: description: The `Content-Location` will contain the URI of the specific revision corresponding to this file resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/file' application/json: schema: $ref: '#/components/schemas/file' '304': $ref: '#/components/responses/304' '404': $ref: '#/components/responses/404File' put: summary: Update this file descriptor description: Perform a complete replacement of this file's descriptor. operationId: updateFile security: - apiKey: [] accessToken: - data/write x-apiture-implemented: true tags: - File parameters: - $ref: '#/components/parameters/fileIdPathParam' - $ref: '#/components/parameters/ifMatchHeaderParam' requestBody: $ref: '#/components/requestBodies/file' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this file resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/file' application/json: schema: $ref: '#/components/schemas/file' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404File' '412': $ref: '#/components/responses/412' '422': $ref: '#/components/responses/422' patch: summary: Update this file's descriptor description: >- Perform a partial update of this file's descriptor. Fields which are omitted are not updated. Nested `_embedded` and `_links` are ignored if included. operationId: patchFile security: - apiKey: [] accessToken: - data/write x-apiture-implemented: true tags: - File parameters: - $ref: '#/components/parameters/fileIdPathParam' - $ref: '#/components/parameters/ifMatchHeaderParam' requestBody: $ref: '#/components/requestBodies/file' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this file resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/file' application/json: schema: $ref: '#/components/schemas/file' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404File' '412': $ref: '#/components/responses/412' '422': $ref: '#/components/responses/422' delete: summary: Delete this file resource description: Delete this file resource and any resources that are owned by it. operationId: deleteFile security: - apiKey: [] accessToken: - data/delete x-apiture-implemented: true tags: - File parameters: - $ref: '#/components/parameters/ifMatchHeaderParam' - $ref: '#/components/parameters/fileIdPathParam' responses: '204': $ref: '#/components/responses/204Deleted' '404': $ref: '#/components/responses/404File' '412': $ref: '#/components/responses/412' '/files/{fileId}/revisions': get: summary: Return a collection of file revisions description: >- Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting) [filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searchable) collection of file revisions. The [links](https://developer.apiture.com/docs/concepts/links) in the response include pagination links. operationId: getFileRevisions security: - apiKey: [] accessToken: - data/read tags: - File parameters: - $ref: '#/components/parameters/fileIdPathParam' - name: start in: query description: The zero-based index of the first product revision item to include in this page. The default 0 denotes the beginning of the collection. schema: type: integer format: int64 default: 0 - name: limit in: query description: The maximum number of product representations to return in this page. schema: type: integer format: int32 default: 100 - name: sortBy in: query description: >- Optional sort criteria. Revision collections are sorted by default in reverse chronological order (most recent revision first). See [sort criteria format](https://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`. schema: type: string - $ref: '#/components/parameters/filterQueryParam' - $ref: '#/components/parameters/qQueryParam' responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/files' application/json: schema: $ref: '#/components/schemas/files' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404File' '422': $ref: '#/components/responses/422' x-apiture-implemented: true '/files/{fileId}/revisions/{revisionId}': get: summary: Fetch a representation of an immutable revision of this file description: >- Return an immutable [HAL](https://developer.apiture.com/docs/concepts/hal) representation of this revision of this file resource. The revision may also have `prev` and `next` links to previous and/or next revisions, if they exist. operationId: getFileRevision security: - apiKey: [] accessToken: - data/read tags: - File parameters: - $ref: '#/components/parameters/fileIdPathParam' - $ref: '#/components/parameters/revisionIdPathParam' - $ref: '#/components/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this file resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/file' application/json: schema: $ref: '#/components/schemas/file' '304': $ref: '#/components/responses/304' '404': $ref: '#/components/responses/404File' x-apiture-implemented: true '/files/{fileId}/content': get: summary: Return the raw content of the file description: >- Return the raw content of the file as a stream of bytes. This operation normally returns a 302 to redirect the caller to the actual URL where the file content is available. operationId: getFileContent security: - apiKey: [] accessToken: - data/read tags: - File parameters: - $ref: '#/components/parameters/fileIdPathParam' responses: '200': description: OK headers: Content-Type: description: The media type of the file content. schema: type: string content: '*/*': schema: type: string format: binary '302': description: Found. The URL where the file's content is located. This is the most likely response. headers: Location: description: The URL where the file's content is located. schema: type: string '404': $ref: '#/components/responses/404File' '/content/{contentId}': get: summary: Get a shared file's content description: |- `/content/{contentId}` represents the _shared_ URL Return the raw content of the file as a stream of bytes. This operation normally returns a 302 to redirect the caller to the actual URL where the file content is available. In the future, a `delete` method will unshare a file. tags: - File operationId: getSharedContent parameters: - name: contentId description: >- The unique ID that refers to a file's raw content and represents the publicly _shared_ file. This ID is not related to the `{fileId}` and can be revoked when the user decides to unshare a file. in: path required: true schema: type: string responses: '200': description: OK headers: Content-Type: description: The media type of the file content. schema: type: string content: '*/*': schema: type: string format: binary '302': description: Found. The URL where the file's content is located. This is the most likely response. headers: Location: description: The URL where the file's content is located. schema: type: string '404': $ref: '#/components/responses/404File' /uploads: get: summary: Return a collection of recent and in progress uploads description: >- Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting) [filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searchable) collection of uploads. The [links](https://developer.apiture.com/docs/concepts/links) in the response include pagination links. Upload resources expire after a while and these resources are automatically deleted. operationId: getUploads security: - apiKey: [] accessToken: - data/read x-apiture-implemented: true tags: - Upload x-apiture-traits: sortBy: - name itemSchema: upload filters: name: filter: - eq - ne - lt - le - gt - ge - startsWith - endsWith - contains - search _id: filter: - eq - in parameters: - name: start in: query description: 'The zero-based index of the first upload in this page. The default, 0, represents the first page of the collection.' schema: type: integer format: int64 default: 0 - name: limit in: query description: The maximum number of upload representations to return in this page. schema: type: integer format: int32 default: 100 - name: sortBy in: query description: >- Optional sort criteria. See [sort criteria format](https://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.
This collection may be sorted by following properties:
• `name` schema: type: string - name: name in: query description: >- Subset the uploads collection to those with this name value. Use `|` to separate multiple values. For example, `?name=Bartell` matches only items whose name is Bartell; `?name=Bartell|kirsten` matches items whose name is Bartell or kirsten. This is combined with an implicit and with other filters if they are used. See [filtering](https://developer.apiture.com/docs/concepts/filtering). schema: type: string - name: filter in: query description: >- Optional filter criteria. See [filtering](https://developer.apiture.com/docs/concepts/filtering).
This collection may be filtered by following properties and functions:
• Property `name` using functions `eq`, `ne`, `lt`, `le`, `gt`, `ge`, `startsWith`, `endsWith`, `contains`, `search`
• Property `_id` using functions `eq`, `in` schema: type: string - $ref: '#/components/parameters/qQueryParam' responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/uploads' application/json: schema: $ref: '#/components/schemas/uploads' '400': $ref: '#/components/responses/400' '422': $ref: '#/components/responses/422' post: summary: Create a new upload description: >- Create a new file upload tracker. The caller provides a list of one or more files to be uploaded in `_embedded.items`.

This operation returns a modified _upload tracker_ resource representation which contains embedded file descriptors. Each file descriptor contain the file name, type, etc. and a link named `apiture:uploadUrl` which points to an upload URL. The client must `PUT` the file content to those respective URLs to complete the uploads.

The `state` of the upload tracker shows the upload status. When the `state` is `completes`, the files associated with the upload will be in this resource's `_embedded` object with the name `files`; that value an array of file descriptor objects.

The target folder in which the file will be stored may be specified in `_links` using the *`apiture:folder`* link relation name.

If there is already a file of the same name in the target folder, the file is renamed by adding or incrementing a unique numeric suffix in parentheses. For example, if `tax-summary-2018.pdf` already exists, uploading a new document with that name will be renamed `tax-summary-2018 (1).pdf`; uploading another file will be renamed `tax-summary-2018 (2).pdf`, and so on.

**TODO** In the future, this API will also support uploading new revisions of the document and maintaining document revision history. operationId: createUpload security: - apiKey: [] accessToken: - data/write x-apiture-implemented: true tags: - Upload requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/createUpload' application/json: schema: $ref: '#/components/schemas/createUpload' description: The data necessary to create a new upload. required: true responses: '201': description: Created headers: Location: description: >- The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with *`scheme`*`://host` schema: type: string format: uri ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/upload' application/json: schema: $ref: '#/components/schemas/upload' '202': description: Accepted headers: Location: description: >- The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with *`scheme`*`://host` schema: type: string format: uri ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/upload' application/json: schema: $ref: '#/components/schemas/upload' '400': $ref: '#/components/responses/400' parameters: [] '/uploads/{uploadId}': get: summary: Fetch a representation of this upload description: 'Return a [HAL](https://developer.apiture.com/docs/concepts/hal) representation of this upload resource.' operationId: getUpload security: - apiKey: [] accessToken: - data/read x-apiture-implemented: true tags: - Upload parameters: - $ref: '#/components/parameters/uploadIdPathParam' - $ref: '#/components/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this upload resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/upload' application/json: schema: $ref: '#/components/schemas/upload' '304': $ref: '#/components/responses/304' '404': $ref: '#/components/responses/404Upload' delete: summary: Delete this upload resource description: >- Delete this upload resource and any resources that are owned by it. Note that deleting an upload does _not_ delete any files that have been uploaded. operationId: deleteUpload security: - apiKey: [] accessToken: - data/delete x-apiture-implemented: true tags: - Upload parameters: - $ref: '#/components/parameters/ifMatchHeaderParam' - $ref: '#/components/parameters/uploadIdPathParam' responses: '204': $ref: '#/components/responses/204Deleted' '404': $ref: '#/components/responses/404Upload' '412': $ref: '#/components/responses/412' '/uploads/{uploadId}/content': post: summary: Upload the file's raw content to the corresponding file resource. operationId: uploadContent security: - apiKey: [] x-apiture-traits: hidden: true tags: - Upload parameters: - $ref: '#/components/parameters/uploadIdPathParam' - name: Content-Type description: The media type describing the file's content type. in: header required: true schema: type: string requestBody: content: '*/*': schema: type: string format: binary multipart/form-data: schema: type: string format: binary description: The file contents as a stream of bytes. required: true description: >- Upload the raw content of the file as a stream of bytes. Examples include the binary bytes for an image or PDF document, or the `multipart/form-data` representation of the file. The `Content-Type` header (or the `Content-Type` in the multipart form data) must match the `contentType` of the file resource. The response is the `/files/{fileId}` file resource, not the file content. *Note*: This is a _hidden_ operation which is a proxy for the `apiture:uploadUrl` link returned when creating a new upload in the `createUpload` operation. Clients should *not* assume this URL exists but should instead use the `apiture:uploadUrl` link that is returned when creating a new upload resource. If the file is in a folder for which revisions are enable, this will create a new revision of the file; see the `getFileRevisions` and `getFileRevision` operations. responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/files' application/json: schema: $ref: '#/components/schemas/files' '400': description: >- Bad Request. The file could not be uploaded. Possible errors are the file is too large, or the file type is not allowed o may be potentially malicious. TODO: define errors with x-apiture-errors This error response may have one of the following `type` values: * [`fileInvalidType`](#err-fileInvalidType) x-apiture-errors: - fileInvalidType content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' '404': $ref: '#/components/responses/404File' '409': description: Conflict. The `Content-Type` did not match the `contentType` of the file resource. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' '412': $ref: '#/components/responses/412' /: get: summary: Top-level resources and operations in this API description: |- Return links to the top-level resources and operations in this API. Links in the root response may include: * *`apiture:files`* : A link to the collection of all files. * *`apiture:folders`* : A link to the collection of all folders. * *`apiture:uploads`* : A link to the collection of all upload tasks. * *`apiture:myFolder`* : A link to the currently authenticated user's primary folder. * *`apiture:myUploads`* : A link to the currently authenticated user's primary upload folder, a child folder of the user's primary folder. operationId: getApi security: - apiKey: [] x-apiture-implemented: true responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/root' application/json: schema: $ref: '#/components/schemas/root' tags: - API parameters: [] /apiDoc: get: summary: Return API definition document description: Return the OpenAPI document that describes this API. operationId: getApiDoc security: - apiKey: [] x-apiture-implemented: true responses: '200': description: OK content: application/json: schema: type: object application/openapi+json;version=2.0: schema: type: object application/openapi+yaml;version=2.0: schema: type: object tags: - API parameters: [] x-apiture-traits: - api: title: Vault basePath: vault links: - getApiDoc - getApi - getFolders - createFolder - getFiles - createFile - getUploads - createUpload - resource: name: upload description: A request to upload one or more files into the file vault. excludeMethods: - put - resource: name: file description: A file (document) residing in the file vault. - resource: name: folder description: Hierarchical folder structures for organizing related files. - security: baseScope: data x-apiture-errors: malformedRequestBody: description: The supplied request body was malformed remediation: Check to make sure that your request body exists and that it does not contain syntax errors folderMissingName: description: Name is missing remediation: Check to make sure that name exists invalidFileId: description: No Files were found for the specified fileId remediation: Check to make sure that the supplied fileId corresponds to an apiture file resource invalidFolderId: description: No Folders were found for the specified folderId remediation: Check to make sure that the supplied folderId corresponds to an apiture folder resource invalidFilesFilter: description: No Files were found with the specified filter remediation: Check to make sure that the supplied filter corresponds to an apiture file resource notEmptyFolder: description: There are files in the folder remediation: Remove files from the folder createStorageFolderFailed: description: Error occurred while trying to create AWS S3 folder remediation: Check to make sure that the supplied bucket and folderName are valid and resolve any errors in _error fileInvalidCategory: description: Category is invalid remediation: Check to make sure that category corresponds to an enum value fileInvalidType: description: File type is invalid remediation: Check to make sure the file type matches the specified content type invalidUploadId: description: No Uploads were found for the specified uploadId remediation: Check to make sure that the supplied uploadId corresponds to an apiture upload resource servers: - url: 'https://api.devbank.apiture.com/vault' components: parameters: folderIdPathParam: name: folderId description: The unique identifier of this folder. This is an immutable opaque string. in: path required: true schema: type: string filterQueryParam: name: filter in: query description: 'Optional filter criteria. See [filtering](https://developer.apiture.com/docs/concepts/filtering).' schema: type: string folderQueryParam: name: folder in: query description: Subset the response to resources that reside directly within the specified folder. The value may be a folder ID or a folder URI. schema: type: string qQueryParam: name: q in: query description: 'Optional search string. See [searching](https://developer.apiture.com/docs/concepts/searching).' schema: type: string typeQueryParam: name: type in: query description: >- Subset the files collection to those with this exact type value. Use `|` to separate multiple values. For example, `?type=Personal%20Savings` matches only items whose type is Personal Savings; `?type=Personal%20Savings|Investment%20Account` matches items whose type is Personal Savings or Investment Account. This is combined with an implicit and with other filters if they are used. See [filtering](https://developer.apiture.com/docs/concepts/filtering). schema: type: string fileIdPathParam: name: fileId description: The unique identifier of this file. This is an opaque string. in: path required: true schema: type: string revisionIdPathParam: name: revisionId description: 'The identifier for a revision of this resource. Revision identifiers use ISO 8601 format: `YYYY-MM-DDThh:mm:ss.sssZ`.' in: path required: true schema: type: string uploadIdPathParam: name: uploadId description: The unique identifier of this upload. This is an opaque string. in: path required: true schema: type: string ifMatchHeaderParam: name: If-Match description: The entity tag that was returned in the `ETag` response. This must match the current entity tag of the resource. in: header schema: type: string ifNoneMatchHeaderParam: name: If-None-Match description: >- The entity tag that was returned in the `ETag` response. If the resource's current entity tag matches, the `GET` will return 304 (Not Modified) and no response body, else the resource representation will be returned. in: header schema: type: string responses: '304': description: Not Modified. The resource has not been modified since it was last fetched. '400': description: >- Bad Request. The request body or one or more of the query parameters was not well formed. The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' '412': description: >- Precondition Failed. The supplied `if-Match` header value does not match the most recent `ETag` response header value. The resource has changed in the interim. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' '422': description: >- Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400CreateFile: description: >- Bad Request. The request body or one or more of the query parameters was not well formed. The `_error` field in the response will contain details about the request error. This error response may have one of the following `type` values: * [`fileInvalidCategory`](#err-fileInvalidCategory) x-apiture-errors: - fileInvalidCategory content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 404Folder: description: >- Not Found. There is no such folder resource at the specified `{folderId}` The `_error` field in the response will contain details about the request error. This error response may have one of the following `type` values: * [`invalidFolderId`](#err-invalidFolderId) x-apiture-errors: - invalidFolderId content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 404File: description: >- Not Found. There is no such file resource at the specified `{fileId}` or no such file resources for the specified `{filter}` The `_error` field in the response will contain details about the request error. This error response may have one of the following `type` values: * [`invalidFileId`](#err-invalidFileId) * [`invalidFilesFilter`](#err-invalidFilesFilter) x-apiture-errors: - invalidFileId - invalidFilesFilter content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 404Upload: description: >- Not Found. There is no such upload resource at the specified `{uploadId}` The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409Folder: description: |- Conflict. A conflict can occur if a folder being deleted contains files. This error response may have one of the following `type` values: * [`notEmptyFolder`](#err-notEmptyFolder) * [`invalidUploadId`](#err-invalidUploadId) x-apiture-errors: - notEmptyFolder - invalidUploadId content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 204Deleted: description: No Content. The resource was deleted successfully. requestBodies: folder: content: application/hal+json: schema: $ref: '#/components/schemas/folder' application/json: schema: $ref: '#/components/schemas/folder' required: true file: content: application/hal+json: schema: $ref: '#/components/schemas/file' application/json: schema: $ref: '#/components/schemas/file' required: true securitySchemes: apiKey: type: apiKey name: API-Key in: header description: >- API Key based authentication. Each client application must pass its private, unique API key, allocated in the developer portal, via the `API-Key: {api-key}` request header. accessToken: type: oauth2 description: >- OAuth2 client access token authentication. The client authenticates against the server at `authorizationUrl`, passing the client's private `clientId` (and optional `clientSecret`) as part of this flow. The client obtains an access token from the server at `tokenUrl`. It then passes the received access token via the `Authorization: Bearer {access-token}` header in subsequent API calls. The authorization process also returns a refresh token which the client should use to renew the access token before it expires. flows: authorizationCode: authorizationUrl: 'https://auth.devbank.apiture.com/auth/oauth2/authorize' tokenUrl: 'https://api.devbank.apiture.com/auth/oauth2/token' scopes: data/read: 'Read access to non-account, non-profile data.' data/write: 'Write (update) access to non-account, non-profile data.' data/delete: 'Delete access to non-account, non-profile data.' data/full: 'Full access to non-account, non-profile data.' schemas: folderFields: title: Folder Fields (v1.0.0) description: Core fields of the folder resource. This model schema is used to construct other model schema. properties: name: description: >- The folder name, for identification purposes. This is limited to 64 characters and may not contain certain special characters such as / or \\. If omitted, the system will assign a name. type: string maxLength: 64 description: description: A description of this folder and its contents. type: string maxLength: 4096 type: description: An optional folder type which describes the intended use or role of the folder and its contents. type: string revisionsEnabled: description: >- If `true`, files in this folder maintain revisions. This property may not be changed after a folder has been created. Moving a file from a folder which has revisions enable to one that has them disabled will result in the loss of the revisions. type: boolean default: false example: name: My uploads description: Default folder where new files are uploaded type: any x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/folderFields/v1.0.0/schema.json' x-apiture-namespace: vault summaryFolder: title: Folder Summary (v1.0.0) description: >- Summary representation of a folder resource in folders collections. This representation normally does not contain any `_embedded` objects. If needed, call the `GET` operation on the item's `self` link to get `_embedded` objects. allOf: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/folderFields' - type: object properties: _id: description: The unique identifier for this folder resource. This is an immutable opaque string. readOnly: true type: string example: _id: 0cbd28ca-27f7-47fa-a223-ce4f91dcc2b2 _profile: 'https://production.api.apiture.com/schemas/vault/summaryFolder/v1.0.0/profile.json' _links: self: href: 'https://api.devbank.apiture.com/vault/folders/0cbd28ca-27f7-47fa-a223-ce4f91dcc2b2' name: 'My upload''https://api.devbank.apiture.coms''' description: Default folder where new files are uploaded. type: any x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/summaryFolder/v1.0.0/schema.json' x-apiture-namespace: vault createFolder: title: Create Folder (v1.0.0) description: |- Representation used to create a new folder. When creating a new folder, the request may contain the following links: * *`apiture:folder`* : The `href` is the URI of the desired parent folder. The user must have permission to add a subfolder to the parent folder. required: - name allOf: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/folderFields' example: _profile: 'https://api.apiture.com/schemas/vault/createFolder/v1.0.0/profile.json' name: My account application documents description: Default folder for account application documents. type: any _links: 'apiture:folder': href: 'https://api.devbank.apiture.com/vault/folders/0cbd28ca-27f7-47fa-a223-ce4f91dcc2b2' x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/createFolder/v1.0.0/schema.json' x-apiture-namespace: vault updateFolder: title: Update Folder (v1.1.0) description: >- Representation used to update or patch a folder. **Note**: The folder's `revisionsEnabled` property is _immutable_.
**Warning**: The schema `updateFolder` was deprecated on version `v0.11.0` of the API. Use `folder` schema instead. `updateFolder` will be removed on version `v0.12.0` of the API. x-apiture-version: 1.1.0 x-apiture-deprecated: since: 0.11.0 removeOn: 0.12.0 replacement: '`folder` schema' allOf: - $ref: '#/components/schemas/folder' example: _id: c78e62e9-9380-4432-8f6c-99a8710b2f74 _profile: 'https://api.apiture.com/schemas/vault/updateFolder/v1.1.0/profile.json' name: My account application documents description: Default folder for account application documents type: any _links: 'apiture:folder': href: 'https://api.devbank.apiture.com/vault/folders/0cbd28ca-27f7-47fa-a223-ce4f91dcc2b2' folder: title: Folder (v1.0.0) description: >- Hierarchical folder structures for organizing related files and folders. A folder has a parent folder, a set of files, and a set of child folders. Links in a folder resource: * *`apiture:folder`* : links to the parent folder, if the folder has a parent. * *`apiture:files`* : links to the collection of files in the folder; this may be empty. * *`apiture:children`* : links to the collection of subfolder whose parent is this folder; this may be empty. allOf: - $ref: '#/components/schemas/summaryFolder' - type: object properties: _id: description: This folder's unique ID. readOnly: true type: string fileCount: description: The number of files in this folder. type: integer readOnly: true folderCount: description: The number of subfolders of this folder type: integer readOnly: true createdAt: description: The date-time when the folder was created or uploaded. type: string format: date-time readOnly: true example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/vault/folder/v1.0.0/profile.json' _links: self: href: 'https://api.devbank.apiture.com/vault/folders/0cbd28ca-27f7-47fa-a223-ce4f91dcc2b2' 'apiture:folder': href: 'https://api.devbank.apiture.com/vault/folders/0094eabb-75e8-49f6-b8f4-0af7cb69eb55' 'apiture:files': href: 'https://api.devbank.apiture.com/vault/files?folder=0cbd28ca-27f7-47fa-a223-ce4f91dcc2b2' 'apiture:children': href: 'https://api.devbank.apiture.com/vault/folders?folder=0cbd28ca-27f7-47fa-a223-ce4f91dcc2b2' _embedded: {} name: My uploads createdAt: '2018-01-04T08:22:24.375Z' type: any x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/folder/v1.0.0/schema.json' x-apiture-namespace: vault folders: title: Folder Collection (v1.0.0) description: >- Collection of folders. The items in the collection are ordered in the `_embedded` object with name `items`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`). allOf: - $ref: '#/components/schemas/collection' - type: object properties: _embedded: type: object description: Embedded objects. properties: items: description: An array containing a page of folder items. type: array items: $ref: '#/components/schemas/summaryFolder' example: _profile: 'https://api.apiture.com/schemas/vault/folders/v1.0.0/profile.json' start: 0 limit: 100 count: 17 name: folders _links: self: href: 'https://api.devbank.apiture.com/vault/folders?start=0&limit=100' first: href: 'https://api.devbank.apiture.com/vault/folders?start=0&limit=10' next: href: 'https://api.devbank.apiture.com/vault/folders?start=100&limit=100' collection: href: 'https://api.devbank.apiture.com/vault/folders' _embedded: items: - name: ... description: ... _links: self: href: ... x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/folders/v1.0.0/schema.json' x-apiture-namespace: vault fileFields: title: File Fields (v1.1.0) description: Core fields of the file resource. This model schema is used to construct other model schema. x-apiture-version: 1.1.0 properties: name: description: >- The file name, for identification purposes. File names may include file extensions such as `.pdf` for PDF documents, although the system does not validate or ensure that extensions match the file content type. This is limited to 64 characters and may not contain certain special characters such as / or \\. If omitted, the system will assign a name. type: string maxLength: 64 description: description: A description of this file and its contents. type: string maxLength: 4096 type: description: >- The document type as determined by the business use case. Unlike the contentType, this indicates what the document content represents (such as a `processedCheckImage`, `mobileCheckDepositImageFront`, etc.). type: string sizeBytes: description: >- The file size in bytes. When creating an upload, the caller can pass this in to indicate the file's size. The services uses this to generate a more accurate upload progress as a percentage of the total upload size. It is not enforced (that is, the actual upload size does not have to match this value). type: integer contentType: description: >- The [media type](https://tools.ietf.org/html/rfc6838) for this file. For text documents, the content type should include the text encoding; if omitted, the encoding type is assumed to be utf-8. type: string example: application/pdf revisionId: description: >- The revision identifier for this file, if this file is in a folder that has revisions enabled. This is an ISO 8601 formatted date-time string, `yyyy-mm-ddTHH:MM:SS.sssZ`. This field is immutable. type: string readOnly: true example: '2018-08-22T11:34:14.375Z' externalId: description: 'If using external data hosting, externalId is used as a lookup key' type: string readOnly: true example: bdca053e-399a-462b-bbb1-18c2682b1087 category: description: 'Required document category, within the enum of options. Required for compliance to categorize PII documents.' type: string enum: - driversLicense - militaryIdentification - passport - socialSecurityCard - stateIdentification - taxForm - utilityBill - applicationFile - entityAuthorization - articlesOfOrganization - supportingDocument example: driversLicense x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/fileFields/v1.1.0/schema.json' x-apiture-namespace: vault summaryFile: title: File Summary (v1.1.0) description: >- Summary representation of a file resource in files collections. This representation normally does not contain any `_embedded` objects. If needed, call the `GET` operation on the item's `self` link to get `_embedded` objects. x-apiture-version: 1.1.0 allOf: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/fileFields' - $ref: '#/components/schemas/revisionEffectiveInterval' - type: object properties: _id: description: The unique identifier for this file resource. This is an immutable opaque string. readOnly: true type: string example: _id: 7dc00a42-76f9-4bbb-bda3-bd6ed203c01b _profile: 'https://api.apiture.com/schemas/vault/summaryFile/v1.1.0/profile.json' _links: self: href: 'https://api.devbank.apiture.com/vault/files/0399abed-fd3d-4830-a88b-30f38b8a365c' 'apiture:folder': href: 'https://api.devbank.apiture.com/vault/folders/0094eabb-75e8-49f6-b8f4-0af7cb69eb55' name: avatar.png description: My personal avatar contentType: image/png type: profilePicture x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/summaryFile/v1.1.0/schema.json' x-apiture-namespace: vault createFile: title: Create File (v1.1.0) description: |- Representation used to create a new file. When creating a file, one can specify a link to the parent folder: * *`apiture:folder`* A link to the desired target folder. The user must have permission to add files to this folder. x-apiture-version: 1.1.0 required: - name - category allOf: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/fileFields' example: _profile: 'https://api.apiture.com/schemas/vault/createFile/v1.1.0/profile.json' name: avatar.png contentType: image/png description: My personal avatar type: profilePicture _links: 'apiture:folder': href: 'https://api.devbank.apiture.com/vault/folders/0094eabb-75e8-49f6-b8f4-0af7cb69eb55' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/createFile/v1.1.0/schema.json' x-apiture-namespace: vault updateFile: title: Update File (v1.1.0) description: >- Representation used to update or patch a file.
**Warning**: The schema `updateFile` was deprecated on version `v0.11.0` of the API. Use `folder` schema instead. `updateFile` will be removed on version `v0.12.0` of the API. x-apiture-deprecated: since: 0.11.0 removeOn: 0.12.0 replacement: '`folder` schema' x-apiture-version: 1.1.0 allOf: - $ref: '#/components/schemas/file' example: _id: 7dc00a42-76f9-4bbb-bda3-bd6ed203c01b _profile: 'https://api.apiture.com/schemas/vault/updateFile/v1.1.0/profile.json' name: myAvatar.png description: My personal avatar file: title: File (v1.1.0) description: |- Representation of a file (document) resource residing in the file vault. A file may have the following links: * *`apiture:folder`* : The folder where the file resides. * *`apiture:share`* : The publicly shared URI of the file's content. * *`apiture:content`* : The direct URI of the file's content * *`apiture:uploadUrl`* : The URL which is used to upload the file content with `PUT`. This link only exists when this file representation is included within an upload tracker. * *`apiture:revisions`* : The previous revisions of this file, if any. x-apiture-version: 1.1.0 allOf: - $ref: '#/components/schemas/summaryFile' - type: object properties: createdAt: description: The date-time when the file was created or uploaded. type: string format: date-time readOnly: true sizeBytes: description: The file size in bytes. This is a derived property and cannot be modified in updates. type: number readOnly: true example: _id: 7dc00a42-76f9-4bbb-bda3-bd6ed203c01b _profile: 'https://api.apiture.com/schemas/vault/file/v1.1.0/profile.json' _links: self: href: 'https://api.devbank.apiture.com/vault/files/7dc00a42-76f9-4bbb-bda3-bd6ed203c01b' 'apiture:folder': href: 'https://api.devbank.apiture.com/vault/folders/0094eabb-75e8-49f6-b8f4-0af7cb69eb55' 'apiture:content': href: 'https://api.devbank.apiture.com/vault/files/7dc00a42-76f9-4bbb-bda3-bd6ed203c01b/content' type: images/png 'apiture:share': href: 'https://api.devbank.apiture.com/vault/content/6b580037-2d4f-4b91-bb3f-175b668fb856.png' _embedded: {} name: avatar.png contentType: image/png description: My personal avatar type: profilePicture sizeBytes: 112800 createdAt: '2018-01-04T07:00:49.375Z' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/file/v1.1.0/schema.json' x-apiture-namespace: vault files: title: File Collection (v1.1.0) description: >- Collection of files. The items in the collection are ordered in the `_embedded` object with name `items`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`). x-apiture-version: 1.1.0 allOf: - $ref: '#/components/schemas/collection' - type: object properties: _embedded: description: Embedded objects. type: object properties: items: type: array items: $ref: '#/components/schemas/summaryFile' example: _profile: 'https://api.apiture.com/schemas/vault/files/v1.1.0/profile.json' start: 0 limit: 100 count: 2 name: files _links: self: href: 'https://api.devbank.apiture.com/vault/files?start=0&limit=100' first: href: 'https://api.devbank.apiture.com/vault/files?start=0&limit=10' next: href: 'https://api.devbank.apiture.com/vault/files?start=100&limit=100' collection: href: 'https://api.devbank.apiture.com/vault/files' _embedded: items: - _profile: 'https://api.apiture.com/schemas/vault/file/v1.1.0/profile.json' _id: 54867739-eca4-434d-8869-8fe6a6248f55 contentType: image/jpg type: checkImageFront description: Image of the front of a mobile check deposit for transaction 3839827893 name: check-front-3839827893.jpg _links: self: href: 'https://api.devbank.apiture.com/vault/files/54867739-eca4-434d-8869-8fe6a6248f55' - _profile: 'https://api.apiture.com/schemas/vault/file/v1.1.0/profile.json' _id: 70955bd8-0bc2-4129-9117-cc7749406cfe contentType: image/jpg type: checkImageBack description: Image of the back of a mobile check deposit for transaction 3839827893 name: check-back-3839827893.jpg _links: self: href: 'https://api.devbank.apiture.com/vault/files/70955bd8-0bc2-4129-9117-cc7749406cfe' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/files/v1.1.0/schema.json' x-apiture-namespace: vault uploadFields: title: Upload Fields (v1.0.0) description: Core fields of the _upload_ resource. This model schema is used to construct other model schema. properties: count: description: The number of files to upload. type: integer minimum: 1 name: description: The name of the items collection in the `items` array in this upload's `_embedded` objects. This should be '`files`'. type: string maxLength: 32 x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/uploadFields/v1.0.0/schema.json' x-apiture-namespace: vault createUpload: title: Create Upload (v1.0.0) description: >- Representation used to create a new upload. The `_embedded.items` array must contain one or more file descriptors with the file `name`, `description`, `type`, and `contentType`. Optional links that are honored in an upload request include the following: * *`apiture:folder`* : The target folder where to uploaded the file(s) should be placed.' required: - _embedded allOf: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/uploadFields' - type: object properties: _embedded: description: A list of the file descriptions which will be uploaded. type: object properties: items: description: An array containing a summary of each file to be uploaded. type: array items: $ref: '#/components/schemas/createFile' example: _profile: 'https://api.apiture.com/schemas/vault/createUpload/v1.0.0/profile.json' count: 2 name: files _embedded: items: - _profile: 'https://api.apiture.com/schemas/vault/file/v1.1.0/profile.json' contentType: image/jpg type: checkImageFront description: Image of the front of a mobile check deposit for transaction 3839827893 name: check-front-3839827893.jpg - _profile: 'https://api.apiture.com/schemas/vault/file/v1.1.0/profile.json' contentType: image/jpg type: checkImageBack description: Image of the back of a mobile check deposit for transaction 3839827893 name: check-back-3839827893.jpg x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/createUpload/v1.0.0/schema.json' x-apiture-namespace: vault summaryUpload: title: Upload Summary (v1.0.0) description: >- Summary representation of an upload tracker resource in the uploads collection. This representation normally does not contain any `_embedded` objects. If needed, call the `GET` operation on the item's `self` link to get `_embedded` objects. allOf: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/uploadFields' - type: object properties: _id: description: The unique identifier for this upload resource. This is an immutable opaque string. readOnly: true type: string example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/vault/summaryUpload/v1.0.0/profile.json' _links: self: href: 'https://api.devbank.apiture.com/vault/uploads/0399abed-fd3d-4830-a88b-30f38b8a365c' count: 2 _embedded: {} x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/summaryUpload/v1.0.0/schema.json' x-apiture-namespace: vault upload: title: Upload (v1.0.0) description: |- A request to start a file upload. Optional links that are honored in an upload request include the following: * *`apiture:folder`* : The target folder for where to upload the file(s) This _upload tracker response_ contains an array of items, one for each file to upload. Each item contains an *`apiture:uploadUrl`* link within the item's `_links`. The client should next `PUT` the file(s) content to the upload URLs to upload each file's contents. x-apiture-todo: 'Include progress info, such as _i_ of _j_ files uploaded and percent complete.' allOf: - $ref: '#/components/schemas/summaryUpload' - type: object properties: name: description: 'The name of the items collection. In this case, the items in the embedded list are ''`files`''.' type: string enum: - files state: description: |- The status of the upload request. * *`pending`* - The upload is pending but has not started * *`started`* - The upload has started * *`completed`* - The upload has completed successfully * *`failed`* - The upload has failed or timed out. type: string enum: - pending - started - completed - failed maximumFileSizeBytes: description: 'The maximum individual file size allowed, in bytes. This is a derived field and ignored in an upload request.' type: integer readOnly: true maximumRequestSizeBytes: description: >- The maximum upload request size allowed, in bytes; this is the total size of the `multipart/form-data` request which is larger than the sum of just the file bytes due to extra metadata and encoding in a `multipart/form-data` request body. This is a derived field and ignored in an upload request. type: integer readOnly: true expiresAt: description: >- The date-time when this upload request expires. If no file is uploaded by this time, this upload request will be deleted and the upload URL in each file descriptor may no longer work. This is a derived field and ignored in an upload request. type: string format: date-time readOnly: true _embedded: description: A list of the file descriptions which will be uploaded. type: object properties: items: description: An array containing a summary of each file to be uploaded. type: array items: $ref: '#/components/schemas/summaryFile' example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/vault/upload/v1.0.0/profile.json' _links: self: href: 'https://api.devbank.apiture.com/vault/uploads/0399abed-fd3d-4830-a88b-30f38b8a365c' 'apiture:folder': href: 'https://api.devbank.apiture.com/vault/folders/0cbd28ca-27f7-47fa-a223-ce4f91dcc2b2' _embedded: items: - contentType: image/jpg type: checkImageFront description: Image of the front of a mobile check deposit for transaction 3839827893 name: check-front-3839827893.jpg _links: 'apiture:uploadUrl': href: 'https://api.devbank.apiture.com/some/opaque/upload/url/for/this/file' - contentType: image/jpg type: checkImageBack description: Image of the back of a mobile check deposit for transaction 3839827893 name: check-back-3839827893.jpg _links: 'apiture:uploadUrl': href: 'https://api.devbank.apiture.com/some/opaque/upload/url/for/this/file' count: 2 name: files state: pending expiresAt: '2017-12-23T00:00:00.000Z' maximumFileSizeBytes: 25000000 maximumReqestSizeBytes: 50000000 x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/upload/v1.0.0/schema.json' x-apiture-namespace: vault uploads: title: Upload Collection (v1.0.0) description: >- Collection of uploads. The items in the collection are ordered in the `_embedded` object with name `items`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`). allOf: - $ref: '#/components/schemas/collection' - type: object properties: _embedded: description: Embedded objects. type: object properties: items: description: An array containing a page of upload items. type: array items: $ref: '#/components/schemas/summaryUpload' example: _profile: 'https://api.apiture.com/schemas/vault/uploads/v1.0.0/profile.json' start: 10 limit: 10 count: 2 name: uploads _links: self: href: 'https://api.devbank.apiture.com/vault/uploads?start=10&limit=10' first: href: 'https://api.devbank.apiture.com/vault/uploads?start=0&limit=10' next: href: 'https://api.devbank.apiture.com/vault/uploads?start=100&limit=100' collection: href: 'https://api.devbank.apiture.com/vault/uploads' 'apiture:myUploads': href: 'https://api.devbank.apiture.com/vault/folders/0cbd28ca-27f7-47fa-a223-ce4f91dcc2b2' _embedded: items: - _id: d3a954aa-2027-4e92-b5b0-136bf31b1837 count: 1 name: files _embedded: - name: image1.png contentType: image/png - name: image2.png contentType: image/png _links: self: href: 'https://api.devbank.apiture.com/vault/uploads/d3a954aa-2027-4e92-b5b0-136bf31b1837' - _id: 70ac012a-d66a-4a2a-8286-916dfda25799 count: 1 name: files _links: self: href: 'https://api.devbank.apiture.com/vault/uploads/70ac012a-d66a-4a2a-8286-916dfda25799' x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/vault/uploads/v1.0.0/schema.json' x-apiture-namespace: vault errorResponse: x-apiture-version: 2.0.0 title: Error Response (v2.0.0) description: 'Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details.' allOf: - $ref: '#/components/schemas/abstractResource' example: _profile: 'https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json' _error: _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3 message: The value for deposit must be greater than 0. statusCode: 422 type: positiveNumberRequired attributes: value: -125.5 remediation: Provide a value which is greater than 0 occurredAt: '2018-01-25T05:50:52.375Z' _links: describedby: href: 'https://api.apiture.com/errors/positiveNumberRequired' _embedded: errors: [] x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json' x-apiture-namespace: common root: x-apiture-version: 2.0.0 title: API Root (v2.0.0) description: 'A HAL response, with hypermedia `_links` for the top-level resources and operations in API.' example: id: apiName name: API name apiVersion: 1.0.0 _profile: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json' _links: {} allOf: - $ref: '#/components/schemas/abstractResource' - type: object properties: _id: description: This API's unique ID. readOnly: true type: string name: type: string description: This API's name. apiVersion: type: string description: This API's version. x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json' x-apiture-namespace: common abstractResource: x-apiture-version: 2.0.0 title: Abstract Resource (v2.0.0) description: >- An abstract schema used to define other schemas for request and response bodies. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either optional domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was successful, this object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded` or any data fields, only `_error` and optionally `_links`. allOf: - $ref: '#/components/schemas/abstractRequest' - type: object properties: _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' readOnly: true example: _profile: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/profile.json' _links: self: href: 'https://api.devbank.apiture.com/applications/application/328f6bf6-d762-422f-a077-ab91ca4d0b6f' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json' x-apiture-namespace: common collection: x-apiture-version: 2.0.0 title: Collection (v2.0.0) description: A collection of resources. This is an abstract model schema which is extended to define specific resource collections. allOf: - $ref: '#/components/schemas/abstractResource' - type: object properties: count: description: >- The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter. type: integer start: description: The start index of this page of items. type: integer limit: description: The maximum number of items per page. type: integer name: description: The name of the collection. type: string x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/collection/v2.0.0/model.json' x-apiture-namespace: common revisionEffectiveInterval: title: Revision Effective Time Interval (v1.0.0) description: Time interval when a resource revision was effective and in use. This schema is used when composing other schemas. x-apiture-version: 1.0.0 type: object properties: effectiveStartAt: description: >- The date-time when this revision was created and became effective. This is an [RFC 3339](https://tools.ietf.org/html/rfc3339) formatted date-time string `YYYY-MM-DDThh:mm:ss.sssZ`. This field is derived and immutable. type: string format: date-time effectiveEndAt: description: >- The date-time when the another revision became effective and this revision ceased being effective. This is an [RFC 3339](https://tools.ietf.org/html/rfc3339) formatted date-time string `YYYY-MM-DDThh:mm:ss.sssZ`. This field is derived and immutable and is not present until the revision is no longer active. type: string format: date-time x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/revisionEffectiveInterval/v1.0.0/model.json' x-apiture-namespace: common abstractRequest: x-apiture-version: 2.0.0 title: Abstract Request (v2.0.0) description: >- An abstract schema used to define other request-only schemas. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation, minus the `_error` defined in `abstractResource`. properties: _links: $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri readOnly: true example: _profile: 'https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/profile.json' _links: self: href: 'https://api.devbank.apiture.com/applications/' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json' x-apiture-namespace: common error: x-apiture-version: 2.0.0 title: Error (v2.0.0) description: Describes an error in an API request or in a service called via the API. required: - message properties: message: type: string description: A localized message string describing the error condition. _id: description: >- A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string. readOnly: true type: string statusCode: description: The HTTP status code associate with this error. type: integer minimum: 100 maximum: 599 example: 422 type: type: string description: >- An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400 Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or `stringValueNotInAllowedSet`. occurredAt: type: string format: date-time description: 'An [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.' example: '2018-02-02T03:37:15.375Z' attributes: description: >- Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the `minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error `type`. allOf: - $ref: '#/components/schemas/attributes' remediation: type: string description: An optional localized string which provides hints for how the user or client can resolve the error. errors: description: An optional array of nested error objects. This property is not always present. type: array items: $ref: '#/components/schemas/error' _links: $ref: '#/components/schemas/links' example: _id: 2eae46e1575c0a7b0115a4b3 message: Descriptive error message... statusCode: 422 type: errorType1 remediation: Remediation string... occurredAt: '2018-01-25T05:50:52.375Z' errors: - _id: ccdbe2c5c938a230667b3827 message: An optional embedded error - _id: dbe9088dcfe2460f229338a3 message: Another optional embedded error _links: describedby: href: 'https://developer.apiture.com/errors/errorType1' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json' x-apiture-namespace: common links: title: Links (v1.0.0) x-apiture-version: 1.0.0 description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' type: object x-apiture-key: linkRelationName additionalProperties: $ref: '#/components/schemas/link' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json' x-apiture-namespace: common attributes: x-apiture-version: 2.0.0 title: Attributes (v2.0.0) description: An optional map of name/value pairs which contains additional dynamic data about the resource. type: object x-apiture-key: attributeName additionalProperties: $ref: '#/components/schemas/attributeValue' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json' x-apiture-namespace: common attributeValue: x-apiture-version: 2.0.0 title: Attribute Value (v2.0.0) description: The data associated with this attribute. x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json' x-apiture-namespace: common link: x-apiture-version: 1.0.0 title: Link (v1.0.0) description: >- Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL links](https://developer.apiture.com/docs/concepts/links), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture links _may_ include a `method` property. required: - href properties: href: type: string format: uri description: The URI or URI template for the resource/operation this link refers to. type: type: string description: The media type for the resource. templated: type: boolean description: 'If true, the link''s href is a [URI template](https://tools.ietf.org/html/rfc6570).' title: type: string description: An optional human-readable localized title for the link. deprecation: type: string format: uri description: 'If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.' profile: type: string format: uri description: 'The URI of a profile document, a JSON document which describes the target resource/operation.' example: href: 'https://api.devbank.apiture.com/applications/application/328f6bf6-d762-422f-a077-ab91ca4d0b6f' title: Application x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json' x-apiture-namespace: common x-apiture-annotated-at: '2020-10-19T15:33:14.856Z'