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.
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_.