--- title: "Archive" description: "Explore comprehensive archive documentation within the Vault platform. Learn about properties, methods, and developer resources. (Gitana 4.0)" product: "Gitana" version: "4.0" url: "/documentation/gitana/4.0/reference/types/archive" --- # Archive An Object 1. [Platform](/documentation/gitana/4.0/reference/types/platform.md) 2. [Vault](/documentation/gitana/4.0/reference/types/vault.md) 3. [Archive](/documentation/gitana/4.0/reference/types/archive.md) ##### Table of Contents - [Overview](#top "Overview") - [Parent](#parent "Parent") - [Properties](#properties "Properties") - [Methods](#methods "Methods") - [Schema](#schema "Schema") > **Note:** Drop in one of our language drivers to accelerate your development. > Here are links to some of our popular [Cookbooks](/documentation/gitana/4.0/developers/cookbooks/overview.md) to help you get started! > > - [C#](/documentation/gitana/4.0/developers/cookbooks/csharp.md) > - [Go](/documentation/gitana/4.0/developers/cookbooks/go.md) > - [Java](/documentation/gitana/4.0/developers/cookbooks/java.md) > - [JavaScript](/documentation/gitana/4.0/developers/cookbooks/javascript2.md) > - [PHP](/documentation/gitana/4.0/developers/cookbooks/php.md) > - [Python](/documentation/gitana/4.0/developers/cookbooks/python.md) > - [Ruby](/documentation/gitana/4.0/developers/cookbooks/ruby.md) ## Parent This Archive is contained within a [Vault](/documentation/gitana/4.0/reference/types/vault.md). ## Properties The following properties are available: | Property | Type | Default | Read-Only | Description | | --- | --- | --- | --- | --- | | \_doc | string | | No | The primary ID | | \_system | object | | No | Metadata maintained by the system | | artifact | string | | No | | | childrenOnly | boolean | | No | | | contents | object | | No | | | dependencies | object | | No | | | endChangeset | string | | No | | | endDate | object | | No | | | group | string | | No | | | includes | object | | No | | | model | string | | No | | | sources | object | | No | | | startChangeset | string | | No | | | startDate | object | | No | | | template | object | | No | | | type | string | | No | | | version | string | | No | | ## Methods The following methods are available: - [Check Permission](#post-vaults-vaultid-archives-archiveid-permissions-permissionid-check "Check Permission") - [Check Single Authority](#post-vaults-vaultid-archives-archiveid-authorities-authorityid-check "Check Single Authority") - [Check multiple Authorities](#post-vaults-vaultid-archives-authorities-check "Check multiple Authorities") - [Check multiple Permissions](#post-vaults-vaultid-archives-permissions-check "Check multiple Permissions") - [Delete Archive](#delete-vaults-vaultid-archives-archiveid "Delete Archive") - [Delete Attachment](#delete-vaults-vaultid-archives-archiveid-attachments-attachmentid "Delete Attachment") - [Download Archive](#get-vaults-vaultid-archives-download "Download Archive") - [Download Attachment](#get-vaults-vaultid-archives-archiveid-attachments-attachmentid "Download Attachment") - [Download Preview](#get-vaults-vaultid-archives-archiveid-preview-name "Download Preview") - [Export Archive](#post-vaults-vaultid-archives-archiveid-export "Export Archive") - [Grant Authority](#post-vaults-vaultid-archives-archiveid-authorities-authorityid-grant "Grant Authority") - [Import Archive](#post-vaults-vaultid-archives-archiveid-import "Import Archive") - [List Attachments](#get-vaults-vaultid-archives-archiveid-attachments "List Attachments") - [Lookup Archives](#get-vaults-vaultid-archives-lookup "Lookup Archives") - [Publish Archive](#post-vaults-vaultid-archives-archiveid-publish "Publish Archive") - [Queries for Archive](#post-vaults-vaultid-archives-query "Queries for Archive") - [Read ACL](#get-vaults-vaultid-archives-archiveid-acl-list "Read ACL") - [Read ACL for Principal](#get-vaults-vaultid-archives-archiveid-acl "Read ACL for Principal") - [Read Archive](#get-vaults-vaultid-archives-archiveid "Read Archive") - [Read Authorities Report](#post-vaults-vaultid-archives-archiveid-authorities "Read Authorities Report") - [Read Copy Archive](#get-vaults-vaultid-archives-archiveid-copy "Read Copy Archive") - [Read Download Archive](#get-vaults-vaultid-archives-archiveid-download "Read Download Archive") - [Revoke Authority](#post-vaults-vaultid-archives-archiveid-authorities-authorityid-revoke "Revoke Authority") - [Unpublish Archive](#post-vaults-vaultid-archives-archiveid-unpublish "Unpublish Archive") - [Update Archive](#put-vaults-vaultid-archives-archiveid "Update Archive") - [Update Archive](#post-vaults-vaultid-archives-archiveid-update "Update Archive") - [Upload Archive](#post-vaults-vaultid-archives "Upload Archive") - [Upload Attachment](#post-vaults-vaultid-archives-archiveid-attachments-attachmentid "Upload Attachment") - [Upload Attachments](#post-vaults-vaultid-archives-archiveid-attachments "Upload Attachments") ### Check Permission Checks whether one or more authorities against the specified archive are granted for a given set of users POST /vaults/{vaultId}/archives/{archiveId}/permissions/{permissionId}/check #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | | permissionId | true | string | The ID of the permission | | id | true | string | | #### Response ```json { "$ref": "#/components/schemas/checkPermission" } ``` ### Check Single Authority Checks whether a single authority is granted against the specified archive for the given user POST /vaults/{vaultId}/archives/{archiveId}/authorities/{authorityId}/check #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | | authorityId | true | string | The ID or authority key for the authority | | id | true | string | | #### Response ```json { "type": "object", "description": "Check", "extends": "status", "properties": { "check": { "type": "boolean" }, "ok": null } } ``` ### Check multiple Authorities Checks whether one or more authorities against the specified archive are granted for a given set of users POST /vaults/{vaultId}/archives/authorities/check #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | #### Response ```json { "type": "object", "description": "Check Multiple Authorities Out", "properties": { "checks": { "type": "array", "items": { "type": "object", "properties": { "permissionedId": { "type": "string" }, "principalId": { "type": "string" }, "authorityId": { "type": "string" }, "result": { "type": "boolean" } } } } } } ``` ### Check multiple Permissions Checks whether one or more permissions against the specified archive are granted for a given set of users POST /vaults/{vaultId}/archives/permissions/check #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | #### Response ```json { "type": "object", "description": "Check Multiple Permissions Out", "properties": { "checks": { "type": "array", "items": { "type": "object", "properties": { "permissionedId": { "type": "string" }, "principalId": { "type": "string" }, "permissionId": { "type": "string" }, "result": { "type": "boolean" } } } } } } ``` ### Delete Archive Deletes an existing Archive DELETE /vaults/{vaultId}/archives/{archiveId} #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | #### Response ```json { "type": "object", "description": "Status of Operation", "properties": { "ok": { "type": "boolean", "description": "Indicates whether the operation succeeded or not" } } } ``` ### Delete Attachment Deletes an attachment DELETE /vaults/{vaultId}/archives/{archiveId}/attachments/{attachmentId} #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | | attachmentId | true | string | | ### Download Archive Downloads an archive, identified by its group, artifact and version IDs GET /vaults/{vaultId}/archives/download #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | groupId | true | string | The ID of the group | | artifactId | true | string | The Artifact ID of the Archive. | | versionId | true | string | The Version ID of the Archive. | After an export job completes, pass the group, artifact and version IDs recorded on the job. ### Download Attachment Downloads an attachment GET /vaults/{vaultId}/archives/{archiveId}/attachments/{attachmentId} #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | | attachmentId | true | string | | ### Download Preview Downloads a preview stream of an archive attachment GET /vaults/{vaultId}/archives/{archiveId}/preview/{name} #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | | name | true | string | | ### Export Archive Starts an export job for this resource POST /vaults/{vaultId}/archives/{archiveId}/export #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | | groupId | false | string | The Group ID to be assigned to the exported archive | | artifactId | false | string | The Artifact ID to be assigned to the exported archive | | versionId | false | string | The Version ID to be assigned to the exported archive | | vaultId | false | string | The ID of the vault where the exported archive should be saved | | schedule | false | string | Whether to run the job immediately or in the background (either 'synchronous' or 'asynchronous') | #### Response ```json { "type": "object", "description": "Export Configuration", "properties": { "startDate": { "type": "object", "description": "Only include objects whose modification date is after this time (epoch millis). This is used for partial or rolling exports." }, "endDate": { "type": "object", "description": "Only include objects whose modification date is before this time (epoch millis). This is used for partial or rolling exports." }, "startChangeset": { "type": "string", "description": "Only include data that is relevant to changesets at or beyond the specified changeset." }, "endChangeset": { "type": "string", "description": "Only include data that is relevant to changesets at or before the specified changeset." }, "includeACLs": { "type": "boolean", "default": true, "description": "Whether to include ACLs during export." }, "includeTeams": { "type": "boolean", "default": true, "description": "Whether to include Teams during export." }, "includeActivities": { "type": "boolean", "default": true, "description": "Whether to include Activities during export." }, "includeBinaries": { "type": "boolean", "default": true, "description": "Whether to include Binaries for data stores during export." }, "includeAttachments": { "type": "boolean", "default": true, "description": "Whether to include Attachments for Attachables during export." }, "artifactDependencies": { "type": "array", "items": { "type": "object" } }, "artifactIncludes": { "type": "array", "items": { "type": "object" } }, "forceIncludes": { "type": "boolean" } } } ``` ### Grant Authority Grants an authority against the specified archive to a given user POST /vaults/{vaultId}/archives/{archiveId}/authorities/{authorityId}/grant #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | | authorityId | true | string | The ID or authority key for the authority | | id | true | string | | #### Response ```json { "type": "object", "description": "Status of Operation", "properties": { "ok": { "type": "boolean", "description": "Indicates whether the operation succeeded or not" } } } ``` ### Import Archive Starts an import job for this resource POST /vaults/{vaultId}/archives/{archiveId}/import #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | | groupId | false | string | The Group ID to be assigned to the exported archive | | artifactId | false | string | The Artifact ID to be assigned to the exported archive | | versionId | false | string | The Version ID to be assigned to the exported archive | | vaultId | false | string | The ID of the vault where the exported archive should be saved | | schedule | false | string | Whether to run the job immediately or in the background (either 'synchronous' or 'asynchronous') | #### Response ```json { "type": "object", "description": "Import Configuration", "properties": { "includeACLs": { "type": "boolean", "default": true, "description": "Whether to include ACLs during import." }, "includeTeams": { "type": "boolean", "default": true, "description": "Whether to include Teams during import." }, "includeActivities": { "type": "boolean", "default": true, "description": "Whether to include Activities during import." }, "includeBinaries": { "type": "boolean", "default": true, "description": "Whether to include Binaries for data stores during import." }, "includeAttachments": { "type": "boolean", "default": true, "description": "Whether to include Attachments for Attachables during import." }, "strategy": { "type": "array", "items": { "type": "string" }, "default": "CLONE", "description": "Either CLONE or COPY_EVERYTHING. Use CLONE to keep the same IDs on import. Use COPY_EVERYTHING to generate all new IDs for all entries on every import." }, "substitutions": { "type": "string" } } } ``` ### List Attachments Lists the attachments for an archive GET /vaults/{vaultId}/archives/{archiveId}/attachments #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | ### Lookup Archives GET /vaults/{vaultId}/archives/lookup #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | group | true | string | | | artifact | true | string | | | version | true | string | | ### Publish Archive POST /vaults/{vaultId}/archives/{archiveId}/publish #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | ### Queries for Archive Queries for instances of type Archive POST /vaults/{vaultId}/archives/query #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | sort | false | object | Defines how to sort fields in the result set | | skip | false | number | Skips the result set cursor ahead the specified number of records | | limit | false | number | Specifies the number of records to be handed back in the result set | This method supports pagination. #### Response ```json { "type": "object", "description": "Result Map", "properties": { "total_rows": { "type": "number" }, "offset": { "type": "number" }, "size": { "type": "number" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/resultmap_archive" } } } } ``` ### Read ACL Read the Access Control List for the specified archive GET /vaults/{vaultId}/archives/{archiveId}/acl/list #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | #### Response ```json { "type": "object", "description": "Result Map of ACL entries", "properties": { "total_rows": { "type": "number" }, "offset": { "type": "number" }, "size": { "type": "number" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "_doc": { "type": "string", "title": "Principal ID" }, "name": { "type": "string", "title": "Principal Name" }, "type": { "type": "string", "title": "Principal Type" }, "domainId": { "type": "string" }, "domainQualifiedId": { "type": "string" }, "domainQualifiedName": { "type": "string" }, "principalId": { "type": "string", "title": "Principal ID" }, "userEmail": { "type": "string" }, "userFirstName": { "type": "string" }, "userLastName": { "type": "string" }, "authorities": { "type": "array", "title": "Authorities", "items": { "type": "string", "title": "Authority Key" } } } } } } } ``` ### Read ACL for Principal Read the Access Control List for the specified archive and the given principal GET /vaults/{vaultId}/archives/{archiveId}/acl #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | | id | true | string | | #### Response ```json { "type": "object", "description": "Result Map of Authority Keys", "properties": { "total_rows": { "type": "number" }, "offset": { "type": "number" }, "size": { "type": "number" }, "rows": { "type": "array", "items": { "type": "string", "description": "Authority Key" } } } } ``` ### Read Archive Reads an instance of a Archive GET /vaults/{vaultId}/archives/{archiveId} #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | #### Response ```json { "description": "Archive", "container": "vault", "type": "object", "extends": "document", "properties": { "model": { "type": "string" }, "type": { "type": "string" }, "group": { "type": "string" }, "artifact": { "type": "string" }, "version": { "type": "string" }, "contents": { "type": "object" }, "dependencies": { "type": "object" }, "includes": { "type": "object" }, "startDate": { "type": "object" }, "endDate": { "type": "object" }, "startChangeset": { "type": "string" }, "endChangeset": { "type": "string" }, "sources": { "type": "object" }, "childrenOnly": { "type": "boolean" }, "template": { "type": "object", "properties": { "templateType": { "type": "string" }, "templateKey": { "type": "string" } } }, "_doc": null, "_system": null } } ``` ### Read Authorities Report Read the Authorities Report for the specified archive POST /vaults/{vaultId}/archives/{archiveId}/authorities #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | #### Response ```json { "type": "object", "description": "Authority Report", "properties": { "principalId": { "type": "object", "properties": { "id": { "type": "object", "properties": { "role-key": { "type": "string" }, "principal": { "type": "string" }, "permissioned": { "type": "string" }, "inheritsFrom": { "type": "object", "properties": { "id": { "type": "string" }, "principal": { "type": "string" }, "permissioned": { "type": "string" } } } } } } } } } ``` ### Read Copy Archive GET /vaults/{vaultId}/archives/{archiveId}/copy #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | | targetVaultId | true | string | | ### Read Download Archive GET /vaults/{vaultId}/archives/{archiveId}/download #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | ### Revoke Authority Revokes an authority against the specified archive from a given user POST /vaults/{vaultId}/archives/{archiveId}/authorities/{authorityId}/revoke #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | | authorityId | true | string | The ID or authority key for the authority | | id | true | string | | #### Response ```json { "type": "object", "description": "Status of Operation", "properties": { "ok": { "type": "boolean", "description": "Indicates whether the operation succeeded or not" } } } ``` ### Unpublish Archive POST /vaults/{vaultId}/archives/{archiveId}/unpublish #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | ### Update Archive Updates an existing Archive PUT /vaults/{vaultId}/archives/{archiveId} #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | #### Response ```json { "type": "object", "description": "Status of Operation", "properties": { "ok": { "type": "boolean", "description": "Indicates whether the operation succeeded or not" } } } ``` ### Update Archive Updates an existing Archive POST /vaults/{vaultId}/archives/{archiveId}/update #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | #### Response ```json { "type": "object", "description": "Status of Operation", "properties": { "ok": { "type": "boolean", "description": "Indicates whether the operation succeeded or not" } } } ``` ### Upload Archive Uploads an archive ZIP file to the vault, as a direct ZIP payload or a multi-part POST POST /vaults/{vaultId}/archives #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | group | false | string | | | artifact | false | string | | | version | false | string | | | type | false | string | | | title | false | string | | | description | false | string | | | published | false | string | | The archive may take a few seconds to become available (for example, while it is scanned for viruses). Until then, reading it returns a 404. ### Upload Attachment Uploads an attachment POST /vaults/{vaultId}/archives/{archiveId}/attachments/{attachmentId} #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | | attachmentId | true | string | | ### Upload Attachments Uploads one or more attachments POST /vaults/{vaultId}/archives/{archiveId}/attachments #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | vaultId | true | string | The ID of the vault | | archiveId | true | string | The ID of the archive | ## Schema ```json { "description": "Archive", "container": "vault", "type": "object", "extends": "document", "properties": { "model": { "type": "string" }, "type": { "type": "string" }, "group": { "type": "string" }, "artifact": { "type": "string" }, "version": { "type": "string" }, "contents": { "type": "object" }, "dependencies": { "type": "object" }, "includes": { "type": "object" }, "startDate": { "type": "object" }, "endDate": { "type": "object" }, "startChangeset": { "type": "string" }, "endChangeset": { "type": "string" }, "sources": { "type": "object" }, "childrenOnly": { "type": "boolean" }, "template": { "type": "object", "properties": { "templateType": { "type": "string" }, "templateKey": { "type": "string" } } }, "_doc": null, "_system": null }, "id": "archive" } ```