# Project API Methods

## Projects

Projects serve as special containers for collaboration. Users with ADMINISTER access manage permissions within projects.

### Projects and Containers

Create projects through the web user interface or use the API method `/project/new`. Creating a project outside an organization makes the creator responsible for storage costs and compute time for project jobs. Each project includes metadata (name, description, tags, properties) and can use boolean flags to control data modifications and copying per [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls).

The system creates generic data containers automatically for analysis and data sharing. Each container links to a project or user/organization that pays storage costs.

### Project Metadata

Projects can have names, descriptions, properties, and tags. The DNAnexus Platform sets properties automatically to for optimal user experience.

## Project API Method Specifications

### API method: `/project/new`

#### Specification

Creates a new project and grants ADMINISTER access to the creating user.

#### Inputs

* `name` **string** (required) The name of the project.
* `summary` **string** (optional) A short summary of what the project contains. Defaults to `""`.
* `description` **string** (optional) A longer description of the project. Defaults to `""`.
* `protected` **boolean** (optional) Sets protection for the project. See details in the [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls) section. Defaults to `false`.
* `restricted` **boolean** (optional) Sets restrictions for the project. See details in the [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls) section. Defaults to `false`.
* `downloadRestricted` **boolean** (optional) Controls downloading of data outside the platform. For database objects, controls access to project data from outside DNAnexus. When set to true, `previewViewerRestricted` automatically defaults to true unless explicitly overridden by providing the `previewViewerRestricted` parameter. See details in the [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls) section. Defaults to `false`.
* `previewViewerRestricted` **boolean** (optional) When true, disables [file preview and viewer](https://documentation.dnanexus.com/user/objects/visualizing-data) for the project. This setting automatically defaults to true when `downloadRestricted` is true, but can be explicitly overridden by providing this parameter. See details in the [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls) section.
  * Defaults to `true` when `downloadRestricted` is `true`, otherwise `false`.
* `externalUploadRestricted` **boolean** (optional) When true, rejects data uploads from outside the job context. See [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls) for details. Defaults to `false`.
* `httpsAppIsolatedBrowsing` **boolean** (optional) When true, wraps httpsApp access in Isolated Browsing for project jobs. See [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls) and [Isolated Browsing](https://documentation.dnanexus.com/developer/apps/https-applications/isolated-browsing-for-https-apps) for details. Defaults to `false`.
* `httpsAppIsolatedBrowsingOptions` **mapping** (optional) A mapping with Isolated Browsing options that can be specified only if `httpsAppIsolatedBrowsing` argument is also set to `true`. Mapping, if specified, may contain the following keys. Defaults to `{}`.
  * `pasteFromLocalClipboardMaxBytes` **integer** (optional) Must be between 0 and 262,144 bytes. Specifies the maximum size of the locally copied text that is pasteable in the remote browser. Value of `0` disables pasting of any local text into the remote browser and is the default when `pasteFromLocalClipboardMaxBytes` is not explicitly specified. Defaults to `0`.
* `databaseUIViewOnly` **boolean** (optional) If set to true, project members with VIEW access have their access to project databases restricted to the [Cohort Browser](https://documentation.dnanexus.com/user/cohort-browser) only. Defaults to `false`.
* `containsPHI` **boolean** (optional) Whether to mark the project as containing protected health information (PHI). See more details in the [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls) section. Defaults to `false`.
* `egressBillTo` **string** (optional) Specifies whether to bill egress costs to the project's billTo account or the downloading user's default billTo account. Defaults to `"projectBillTo"`.
  * Must be one of `"projectBillTo"` or `"downloaderBillTo"`.
* `tags` **array of strings** (optional) Tags to associate with the project.
* `properties` **mapping** (optional) Properties to associate with the project.
  * **key** — Property name.
  * **value** **string** — Property value.
* `billTo` **string** (optional) ID of the entity for billing any costs associated with this project. This must be the ID of the requesting user or an org of which the requesting user is a member with `allowBillableActivities` permission. Defaults to the `billTo` of the requesting user.
* `region` **string** (optional) The region where this project is created. The region must be among the permitted regions of the project's `billTo`. For more information about regions, see [Region](https://documentation.dnanexus.com/developer/api/regions). Defaults to the `defaultRegion` of the `billTo` of the project.
* `monthlyComputeLimit` **integer** (optional, nullable) The project-level compute spending limit.
* `monthlyEgressBytesLimit` **integer** (optional, nullable) The project-level egress spending limit.
* `monthlyStorageLimit` **number** (optional, nullable) The project-level storage limit.

{% hint style="info" %}
A license is required to use the Monthly Project Spending Limit for Computing and Egress and Monthly Project Spending Limit for Storage features. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

* `defaultSymlink` **mapping** (optional) Default remote location for new files in the project and all its execution containers. Requires `tmpSymlinkWriteSupport` license enabled for `billTo`.
  * `drive` **string** (required) The drive ID, formatted as "drive-xxxx" and cannot be "drive-PUBLISHED".
  * `container` **string** (required) The container name. This is `region:bucket` for AWS S3 and `containerName` for Azure Blob.
  * `prefix` **string** (optional) The remote location prefix in the container. Defaults to `"/"`.

{% hint style="info" %}
A license is required to use symlinks. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

#### Outputs

* `id` **string** ID of the created project.

#### Errors

* InvalidInput
  * `name` may not be empty and may not match the regex `[\x00-\x1F].`
  * `containsPHI` may not be set to false if the project is marked as containing PHI.
  * `protected`, `restricted`, `downloadRestricted`, `previewViewerRestricted`, `externalUploadRestricted`, `containsPHI`, `databaseUIViewOnly`, `httpsAppIsolatedBrowsing` (if provided) are not booleans.
  * If `httpsAppIsolatedBrowsingOptions` is being set, but `httpsAppIsolatedBrowsing` is not being set to `true`.
  * `httpsAppIsolatedBrowsingOptions` is not a mapping or contains unrecognized keys.
  * `httpsAppIsolatedBrowsingOptions.pasteFromLocalClipboardMaxBytes` is not an integer or within the expected range.
* InvalidState
  * `containsPHI` is true, but the project is in a region that does not support PHI features.
* SpendingLimitExceeded
  * The `billTo` has reached its spending limit.
* OrgExpired
  * The `billTo` organization has expired.
* PermissionDenied
  * One of the following must be supplied: a full scope token, a token with ADMINISTER access in all projects (`"*"`), or a token with the `projectCreation` scope set.
  * If `containsPHI` was set to true, the `billTo` of the project must have PHI features enabled.
  * If `externalUploadRestricted` was set to true, the `billTo` of the project must have the `externalUploadRestrictedControl` license.
  * If `httpsAppIsolatedBrowsing` is being set to `true`, the `billTo` of the project must have the `httpsAppIsolatedBrowsingControl` license.
  * `billTo` must be either the ID of the requesting user or the ID of an org in which the requesting user is a member with `allowBillableActivities` permission.
  * The `billTo` of the invoking user is an org and the user is no longer a member of that org.
  * The `region` that was selected was not among the `permittedRegions` of the `billTo.`

### API method: `/project-xxxx/update`

#### Specification

Updates the specified project with the specified options. Options not supplied in the input hash remain unchanged. For example, if a project has the `protected` flag set, calling this method to update the title or description without the `protected` field preserves the flag's value. Only members with ADMINISTER access can update the project. Updating the `billTo` field resets both `totalSponsoredEgressBytes` and `consumedSponsoredEgressBytes` for the project.

#### Inputs

* `name` **string** (optional) The new name of the project.
* `summary` **string** (optional) The new summary of the project.
* `description` **string** (optional) The new description of the project.
* `protected` **boolean** (optional) The new value of the protected property. See more details in the [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls) section.
* `restricted` **boolean** (optional) The new value of the restricted property. See more details in the [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls) section.
* `downloadRestricted` **boolean** (optional) If set to true, disables the downloading of data outside of the platform. For database objects, it prohibits users from accessing the data in the project from outside DNAnexus. When changed to true on an existing project, `previewViewerRestricted` automatically defaults to true unless explicitly overridden by providing the `previewViewerRestricted` parameter in the same request.
* `previewViewerRestricted` **boolean** (optional) If true, disables [file preview and viewer](https://documentation.dnanexus.com/user/objects/visualizing-data) for this project. When `downloadRestricted` is changed to true, this flag automatically defaults to true, but can be explicitly overridden by providing this parameter in the same request. See [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls) for details.
* `externalUploadRestricted` **boolean** (optional) If true, data uploads to this project from outside the job context are rejected. See [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls) for details. Defaults to `false`.
* `httpsAppIsolatedBrowsing` **boolean** (optional) If true, the jobs in the project have their httpsApp access wrapped in Isolated Browsing. See more details in the [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls) and [Isolated Browsing](https://documentation.dnanexus.com/developer/apps/https-applications/isolated-browsing-for-https-apps) sections. Defaults to `false`.
* `httpsAppIsolatedBrowsingOptions` **mapping** (optional) A mapping with Isolated Browsing options that replaces the existing `httpsAppIsolatedBrowsingOptions` mapping. Can be specified only if the `httpsAppIsolatedBrowsing` argument is also set to `true`. Mapping, if specified, may contain the following keys:
  * `pasteFromLocalClipboardMaxBytes` **integer** (optional) Must be between 0 and 262,144 bytes. Specifies the maximum size of the locally copied text that is pasteable in the remote browser. Value of `0` disables pasting of any local text into the remote browser and is the default when `pasteFromLocalClipboardMaxBytes` is not explicitly specified. Defaults to `0`.
* `containsPHI` **boolean** (optional) Set to true to mark the project as containing protected health information (PHI). See more details in the [Project Data Access Controls](https://documentation.dnanexus.com/getting-started/key-concepts/projects#project-data-access-controls) section.
* `egressBillTo` **string** (optional) The new value for the `egressBillTo` property.
  * Must be one of `"projectBillTo"` or `"downloaderBillTo"`.
* `databaseUIViewOnly` **boolean** (optional) If set to true, project members with VIEW access have their access to project databases restricted to the [Cohort Browser](https://documentation.dnanexus.com/user/cohort-browser) only.
* `version` **integer** (optional) If provided, the value must match the current project's version. Otherwise, the update applies unconditionally.
* `billTo` **string** (optional) ID of the entity to bill for any costs associated with this project. This must be the ID of the requesting user or an org of which the requesting user is a member with `allowBillableActivities` permission.
* `allowedExecutables` **array of strings** (optional, nullable) List of executable IDs permitted for root executions in this project. Set to `null` or omit to remove executable restrictions.
* `monthlyComputeLimit` **integer** (optional, nullable) The project-level compute spending limit. **null** is considered as unlimited, which should be treated as a higher value for any **non-null** defaults.
* `monthlyEgressBytesLimit` **integer** (optional, nullable) The project-level egress spending limit. **null** is considered as unlimited, which should be treated as a higher value for any **non-null** defaults.
* `monthlyStorageLimit` **number** (optional, nullable) The project-level storage spending limit. **null** is considered as unlimited, which should be treated as a higher value for any **non-null** defaults.

{% hint style="info" %}
A license is required to use both the Monthly Project Spending Limit for Computing and Egress feature, and the Monthly Project Spending Limit for Storage feature. Contact [DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

#### Outputs

* `id` **string** ID of the manipulated project.

#### Errors

* ResourceNotFound
  * The specified project does not exist.
* InvalidInput
  * The input is not a hash.
  * `name` (if provided) is not a nonempty string.
  * `summary` (if provided) is not a string.
  * `description` (if provided) is not a string.
  * `protected`, `restricted`, `downloadRestricted`, `previewViewerRestricted`, `externalUploadRestricted`, `containsPHI`, `databaseUIViewOnly`, `httpsAppIsolatedBrowsing` (if provided) are not booleans.
  * `containsPHI` (if provided) cannot be false -- marking a project as no longer containing PHI is unsupported.
  * `containsPHI` is true, but the project is in a region that does not support PHI features.
  * `monthlyComputeLimit` is not an integer and not `null`, or is not larger than zero.\*
  * `monthlyEgressBytesLimit` is not an integer and not `null`, or is not larger than zero.\*
  * `monthlyComputeLimit` is higher than the max value of the org default value and the current `monthlyComputeLimit` and the user is NOT the admin user of the org.\*
  * `monthlyEgressBytesLimit` is higher than the max value of the org default value and the current `monthlyEgressBytesLimit` and the user is NOT the admin user of the org.\*
  * `monthlyStorageLimit` is not a number or `null`, or is not larger than or equal to zero.\*
  * `monthlyStorageLimit` is higher than the org default value and the user is not an org admin.\*
  * `monthlyStorageLimit` is not a number, or `null`, or is not larger than or equal to zero.\*
  * `monthlyStorageLimit` is higher than the max value of the org default value and the current `monthlyStorageLimit`, and the user is not an org admin.\*
* InvalidState
  * `version` was provided and does not match the current version number found in the project.
* PermissionDenied
  * `containsPHI` was set to true, but the `billTo` of the project does not have PHI features enabled.
  * If `externalUploadRestricted` was set to true, the `billTo` of the project must have the `externalUploadRestrictedControl` license.
  * The new billTo must be licensed to use the externalUploadRestricted option.
  * If `httpsAppIsolatedBrowsing` is being set to `true`, the `billTo` of the project must have the `httpsAppIsolatedBrowsingControl` license.
  * The new `billTo` must have the `httpsAppIsolatedBrowsingControl` license for projects with `httpsAppIsolatedBrowsing` set to `true`.
  * `httpsAppIsolatedBrowsingOptions` can only be specified when `httpsAppIsolatedBrowsing` is true
  * `httpsAppIsolatedBrowsingOptions` is not a mapping or contains unrecognized keys.
  * `httpsAppIsolatedBrowsingOptions.pasteFromLocalClipboardMaxBytes` is not an integer or within the expected range.
  * `billTo` must be either the ID of the requesting user or the ID of an org of which the requesting user is a member with `allowBillableActivities` permission.
  * If the requesting user is not one of the project admins or org admins of the project `billTo` org.
  * The `billTo` org of the project does not have `monthlyProjectSpendingLimit` enabled.
  * The `billTo` org does not have `monthlyProjectStorageSpendingLimit` enabled
  * The `billTo` org of the project does not have `monthlyProjectStorageSpendingLimit` enabled
  * The requesting user is neither an ADMIN of the project nor an ADMIN of the billTo org of the project
  * Can not change the billTo of `project-xxxx` while the project contains a [DBCluster](https://documentation.dnanexus.com/developer/api/introduction-to-data-object-classes/dbclusters).
* `billTo` must have the `region` of this project in its `permittedRegions.`
  * If `billTo` is specified and the project is billed to an org, then the requesting user must be a member of the org. Depending on the `restrictProjectTransfer`, the requesting user may be required to be an ADMIN of the org.

{% hint style="info" %}
\* A license is required to use both the Monthly Project Spending Limit for Computing and Egress feature, and the Monthly Project Spending Limit for Storage feature. Contact [DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

### API method: `/project-xxxx/updateSponsorship`

#### Specification

This method modifies specific forms of sponsorship in the project. It can be used to set or modify data egress sponsorship, or used to set or unset third-party data storage sponsorship in the project.

Data egress sponsorship, when set to a specified number of bytes, charges the project's `billTo` for data transferred outside of the system up to that amount, covering data downloaded by users. The billing rate varies based on the downloader's IP range. After exceeding the sponsored bytes limit, the downloader incurs the costs of downloading data from the project.

For projects with data storage sponsorship, the project's `billTo` covers storage charges for all objects in the project. Users or organizations with copies of these data objects in other projects receive free storage until the sponsorship period expires.

Adding data objects to a sponsored project makes them sponsored, and removing them revokes their sponsorship. An object can be sponsored in only one project at a time. Cloning an object into a sponsored project fails if another project sponsors the object.

For sponsored projects, use this method to update the expiration time or terminate sponsorship.

#### Inputs

* `sponsoredUntil` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) or **null** (optional) Sets the expiration time of data storage sponsorship. Specifying **null** (or any time in the past) terminates the sponsorship effective immediately.
* `totalSponsoredEgressBytes` **integer** (optional) Sets the number of bytes to be sponsored for downloads (data egress) from the DNAnexus Platform to an external IP for this project. Users may download up to the specified number of bytes from the project at no cost to themselves, with the cost charged to the project's billTo. If the new value is less than the consumed bytes, the sponsor's charges apply only to completed downloads. Setting this value overrides rather than increments the previous value. To extend the byte limit, invoke this method with a value higher than its previous value.

#### Outputs

* `id` **string** ID of the project.

#### Errors

* InvalidInput
  * `totalSponsoredEgressBytes` must be a non-negative integer.
* InvalidState
  * A data object in the project has third-party sponsorship in another project. Remove the data objects from this project (or from the other project) before applying third-party sponsorship. When this error occurs, the error `details` has the form `{alreadySponsored: [{id: ..., project: ...}, ...]}` indicating the ID and sponsoring project of each third-party sponsored object.
  * A data object in the project has DNAnexus sponsorship.
  * The project is archived.
  * The project has a pending transfer.
* PermissionDenied
  * If `sponsoredUntil` is supplied, the `billTo` of the project requires data sponsorship features. Contact [DNAnexus Support](mailto:support@dnanexus.com) to enable data storage sponsorship features for your account.
  * ADMINISTER access to the project is required.
  * The user's billTo must match the billTo of the project.

### API method: `/project-xxxx/setProperties`

#### Specification

Sets properties on the specified project. To remove a property, set its value to JSON `null` instead of a string. This call updates project properties by merging the available properties with the provided input. The new values take precedence when the same key appears in both sets.

Best practice for resetting properties: Issue a describe call to get the property names, then issue a `setProperties` request to set those property values to `null`. This removes all key/value pairs and allows you to replace them with new ones.

#### Inputs

* `properties` **mapping** (required) Properties to modify.
  * **key** — Name of property to modify.
  * **value** **string or null** — Either a new string value for the property, or `null` to unset the property.

#### Outputs

* `id` **string** ID of the manipulated project, such as "project-xxxx".

#### Errors

* InvalidInput
  * The input is not a hash, `properties` is missing or is not a hash, or there exists at least one value in `properties` which is neither a string nor the JSON `null`.
* ResourceNotFound
  * The specified project does not exist.
* PermissionDenied
  * CONTRIBUTE access required for the specified project.

### API method: `/project-xxxx/describe`

#### Specification

Describes the specified project.

#### Inputs

* `fields` **mapping** (optional) Restrict the output of this method to have only the provided keys in this field.
  * **key** — Desired output field. See the "Outputs" section below for additional valid values here.
  * **value** **boolean** — Whether to include the field.

#### Outputs

* `id` **string** ID of the project, such as "project-xxxx"

The following fields are included by default (but can be disabled using `fields`) :

* `class` **string** The value "project".
* `name` **string** The name of the project.
* `region` **string** The region this project resides in. For more information about regions, see [Regions](https://documentation.dnanexus.com/developer/api/regions).
* `summary` **string** The summary of the project.
* `description` **string** The description of the project.
* `version` **integer** The version number of the project used for tracking changes to its metadata.
* `tags` **array of strings** Tags associated with the project.
* `billTo` **string** ID of the account to which any costs associated with this project is billed.
* `protected` **boolean** The value of the protected flag.
* `restricted` **boolean** The value of the restricted flag.
* `downloadRestricted` **boolean** The value of the `downloadRestricted` flag.
* `previewViewerRestricted` **boolean** The value of the `previewViewerRestricted` flag.
* `externalUploadRestricted` **boolean** The value of the `externalUploadRestricted` flag.
* `httpsAppIsolatedBrowsing` **boolean** The value of the `httpsAppIsolatedBrowsing` flag.
* `httpsAppIsolatedBrowsingOptions` **mapping** A mapping with [Isolated Browsing](https://documentation.dnanexus.com/developer/apps/https-applications/isolated-browsing-for-https-apps) options.
  * `pasteFromLocalClipboardMaxBytes` **integer** Must be between 0 and 262,144 bytes. Specifies the maximum size of the locally copied text that is pasteable in the remote browser. Value of `0` disables pasting of any local text into the remote browser and is the default when `pasteFromLocalClipboardMaxBytes` is not explicitly specified.
* `containsPHI` **boolean** Whether the project is marked as containing protected health information (PHI) and subject to additional restrictions to ensure security and compliance.
* `databaseUIViewOnly` **boolean** If set to true, project members with VIEW access have their access to project databases restricted to the [Cohort Browser](https://documentation.dnanexus.com/user/cohort-browser) only.
* `created` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time at which this project was created.
* `createdBy` **mapping** How the project was created.
  * `user` **string** ID of the user who created the project.
  * `job` **string** ID of the job that created the project.
    * Only present when the project was created by a job.
  * `executable` **string** ID of the applet or app that the job was running.
    * Only present when the project was created by a job.
* `modified` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time at which this project was last updated.
* `level` **string** The highest permission level that the requesting user has.
* `dataUsage` **number** Data usage in GB (not including sponsored data or DBCluster storage). Value updates can experience delays after project changes.
* `defaultInstanceType` **string** Default instance type for apps to run on.
* `sponsoredDataUsage` **number** Sum of DNAnexus-sponsored and third-party sponsored data usage in GB, excluding DBCluster storage. For third-party sponsored projects, objects appear in `dataUsage` rather than `sponsoredDataUsage` since the project's `billTo` handles the billing. Value updates can experience delays after container changes.
* `sponsoredUntil` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Indicates that the project is sponsored by its `billTo` until the specified time. The specified time must be in the future.
  * Only present when the project is sponsored.
* `pendingTransfer` **string** (nullable) If applicable, account ID that has been invited to take the project. Otherwise `null`.
* `totalSponsoredEgressBytes` **integer** The total number of bytes sponsored for this project over the lifetime of the project's current billTo. If this value is less than `consumedSponsoredEgressBytes`, the downloader is billed for additional downloads instead of the sponsor.
* `consumedSponsoredEgressBytes` **integer** The number of sponsored bytes used to transfer files from this project out of the DNAnexus Platform, over the lifetime of the project's current billTo.
* `allowedExecutables` **array of strings** If present, the set of executable IDs that are allowed to run as root executions in this project.

The following fields (included by default) are available if the requesting user has UPLOAD+ access to the project:

* `atSpendingLimit` **boolean** Indicates whether the `billTo` of the project is at their spending limit (and therefore functionality is restricted).

The following fields (included by default) are available if the requesting user has permissions to view the pricing model of the `billTo` of the project:

* `storageCost` **number** Storage cost (in dollars) of the project per month based on data usage (the total cost of an account's projects may be smaller than the sum of this value over all projects if any objects are shared between the projects).

The following fields are only returned if the corresponding field in the `fields` input is set to true:

* `folders` **array of strings** List of all folders in the project.
* `objects` **integer** The number of visible objects in the project.
* `permissions` **mapping** Who has permissions to access this project.
  * **key** — Entity ID. A user or org ID.
  * **value** **string** — The permission level.
    * Must be one of `"VIEW"`, `"UPLOAD"`, `"CONTRIBUTE"`, or `"ADMINISTER"`.
* `egressBillTo` **string** The value of the `egressBillTo` property.
* `appCaches` **mapping** List of containers attached to the project that have been created for running apps.
  * **key** — App ID.
  * **value** **string** — ID of the app ID's project cache container.
* `properties` **mapping** Properties associated with the project.
  * **key** — Property name.
  * **value** **string** — Property value.
* `fileUploadParameters` **mapping** Information about what part sizes and numbers should be used to upload files in this project. See the section Limits on Parts of the Files API for more information about interpreting this. Mapping with the key/values:
  * `minimumPartSize` **integer** Minimum part size, in bytes, that applies to all parts except the part with the highest index. (Clients may assume that if `emptyLastPartAllowed` is false, then `minimumPartSize` is at least 1, that is, the constraint on the last part is no stronger than the constraint on previous parts.)
  * `maximumPartSize` **integer** Maximum part size, in bytes.
  * `emptyLastPartAllowed` **boolean** If true, then the minimum number of parts is 1 and the part with the highest index may contain 0 bytes. If false, then the minimum number of parts is 0 and the part with the highest index must contain at least 1 byte. All parts other than the part with the highest index must still have minimum size given by `minimumPartSize`. If true, then the client can upload a 0-byte file by invoking /file-xxxx/upload once with a part of size 0. If false, then the client can upload a 0-byte file by *not* invoking /file-xxxx/upload at all.
  * `maximumNumParts` **integer** The maximum number of parts that may be uploaded (also equal to the largest permissible part index).
  * `maximumFileSize` **integer** The maximum size of the file, in bytes.
* `availableInstanceTypes` **mapping** Instances available in the project for apps and applets to run on.
  * **key** — Instance type.
  * **value** **mapping** — Contains information on the instance type.
    * `numCores` **integer** Number of cores.
    * `totalMemoryMB` **integer** Memory size in MB.
    * `ephemeralStorageGB` **integer** Storage size in GB.
    * `os` **array of mappings** Supported operating systems. Each value is a mapping with the following fields, indicating one of the supported operating systems:
      * `distribution` **string** The Linux operating system distribution. Must match the `distribution` of the run specifications of the app or the applet to be run.
      * `release` **string** The Linux operating system release. Must match the `release` of the run specifications of the app or the applet to be run.
    * `rank` **integer** Ranking of the instance type based on its value, with rank value of 1 being least valuable.
* `metadataCapacity` **number** Value of `metadataCapacity`. Between 0 and 1, with a 1 indicating the project is at maximum metadata capacity and cannot accept additional metadata.

The following fields are only returned if the corresponding field in the `fields` input is set to true and the `billTo` of the project has `dataCatalog` feature enabled:

* `dataCatalog` **string** (nullable) The ID of the [data catalog](https://documentation.dnanexus.com/developer/api/omics-data-catalog) the project belongs to, or `null` if the project is not associated with a data catalog.

The following fields (included by default) are available if the requesting user has permissions to view the pricing model of the `billTo` of the project and the `billTo` of the project has `monthlyProjectSpendingLimit` enabled:

* `monthlyComputeLimit` **integer** (nullable) The current monthly project spending limit for compute.
* `monthlyEgressBytesLimit` **integer** (nullable) The current monthly project spending limit for egress.
* `currentMonthComputeAvailableBudget` **number** (nullable) The current month's project available spending budget for compute.
* `currentMonthEgressBytesAvailableBudget` **number** (nullable) The current month's project available spending budget for egress.
* `currentMonthComputeUsage` **number** The current month's project usage for compute.
* `currentMonthEgressBytesUsage` **number** The current month's project usage for egress.

The following fields (included by default) are available if the requesting user has permissions to view the pricing model of the `billTo` of the project and the `billTo` of the project has `monthlyProjectStorageSpendingLimit` enabled:

* `monthlyStorageLimit` **number** (nullable) The current monthly project spending limit for storage
* `currentMonthStorageAvailableBudget` **number** (nullable) The current month's project available spending budget for storage
* `currentMonthExpectedStorageUsage` **number** The current month's projected usage for storage

{% hint style="info" %}
Licenses are required for both the Monthly Project Spending Limit for Computing and Egress feature, and the Monthly Project Spending Limit for Storage feature. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

#### Errors

* ResourceNotFound
  * The specified project does not exist.
* InvalidInput
  * Input is not a hash, or `fields` if present, is not a hash or has a non-boolean key.
* PermissionDenied
  * Must have at least VIEW access to the project, be the `billTo` with a full scope token (if the `billTo` is a user) , or be an admin of the `billTo` with a full scope token (if the `billTo` is an org).

### API method: `/project-xxxx/destroy`

#### Specification

Destroys the specified project. All objects in the project are removed.

For jobs not in a terminal state (not done, failed, or terminated), the system throws an InvalidState error unless the `terminateJobs` option is set to force termination.

#### Inputs

* `terminateJobs` **boolean** (optional) Whether to force the destruction of the project and terminate all non-terminal jobs. Defaults to `false`.

#### Outputs

* `id` **string** ID of the manipulated project.

#### Errors

* ResourceNotFound
  * The specified project does not exist.
* PermissionDenied
  * The requesting user is neither an ADMIN of the project nor an ADMIN of the billTo org of the project
* InvalidInput
  * `terminateJobs` (if present) is not a boolean.
* InvalidState
  * `terminateJobs` was not set to true, and there still remain jobs which are not in a terminal state.
  * The project is sponsored (sponsorship must be terminated before the project may be destroyed).

### API method: `/project-xxxx/addTags`

#### Specification

Tags the project with the given strings. Previously applied tags remain unaffected.

#### Inputs

* `tags` **array of strings** (required) Tags to be added.

#### Outputs

* `id` **string** ID of the manipulated project.

#### Errors

* ResourceNotFound
  * The specified project does not exist.
* InvalidInput
  * `tags` is not present or is not a list of nonempty strings.
* PermissionDenied
  * CONTRIBUTE access required.

### API method: `/project-xxxx/removeTags`

#### Specification

Removes the given tags from the project. Tags that do not exist have no effect when removed.

#### Inputs

* `tags` **array of strings** (required) Tags to be removed.

#### Outputs

* `id` **string** ID of the manipulated project.

#### Errors

* ResourceNotFound
  * The specified project does not exist.
* InvalidInput
  * `tags` is not present or is not a list of nonempty strings.
* PermissionDenied
  * CONTRIBUTE access required.

### API method: `/project-xxxx/countRootExecutions`

#### Specification

Counts the root executions in this project that were created within the last 7 days by state. Returns an object whose keys are execution states, and whose values are the number of root executions that are in that state.

#### Inputs

* None

#### Outputs

* **key** — State.
* **value** **integer** — Number of root executions in that state.

#### Errors

* ResourceNotFound
  * The specified project does not exist.
* PermissionDenied
  * VIEW access required.

### API method: `/system/getProjectTags`

#### Specification

Returns the tags on all visible projects. The initial implementation includes only public projects.

#### Inputs

* None

#### Outputs

* **key** — Tag.
* **value** **integer** — Number of projects with the tag.

#### Errors

* No errors are returned.

### API method: `/project-xxxx/archive`

{% hint style="info" %}
A license is required to use the DNAnexus Archive Service. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

#### Specification

Requests for a set of files to be archived on the platform. For each file, if this is the last copy of a file to have archival requested, this triggers the full archival of the object. Otherwise, the file receives an `archival` state marking that archival has been requested.

#### Inputs

* `files` **array of strings** (optional) A subset list of files that should be archived. Example: `'{"files": ["file-xxxx", "file-yyyy"], "allCopies": true}'`. Mutually exclusive with `folder`.
* `folder` **string** (optional) The folder which contains all files that should be archived. Example: `'{"folder" : "/folder1"}'`. Mutually exclusive with `files` and required when `files` not present.
* `recurse` **boolean** (optional) If true, archive all files in subfolders of `folder`. If false, only archive files in `folder`. `folder` must be set. Defaults to `true`.
* `allCopies` **boolean** (optional) This flag forces the transition of files into the `archived` state. Requesting user must be the `ADMIN` of the project `billTo` org. If true, archive all the copies of files in projects with the same `billTo` org. If false, only the copy of the file in the current project transitions to the `archival` state, while other copies of the file in the rest projects with the same `billTo` org remain in the `live` state. Defaults to `false`.

{% hint style="info" %}
While `files` and `folder` are optional on their own, one of them is required.
{% endhint %}

#### Outputs

* `id` **string** The id of the project.
* `count` **integer** The number of files to be tagged for archival.

#### Errors

* InvalidInput
  * if both `files` and `folder` are provided
  * one or more files in key `files` of the input contain symlinks
* InvalidState
  * one or more files is in an "open" ("non-closed") state
  * one or more files is being used as `bundledDepends` for applets
* ResourceNotFound
  * the specified project does not exist.
  * a file or folder does not exist.
* PermissionDenied
  * CONTRIBUTE access required.
  * Must be an org ADMIN of the project `billTo` org to use the `allCopies` options.

### API method: `/project-xxxx/unarchive`

{% hint style="info" %}
A license is required to use the DNAnexus Archive Service. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

#### Specification

Requests for a set of files to be unarchived on the platform. This is an asynchronous command. The requested copy transitions to the live state while all other copies move to the `archival` state.

#### Inputs

* `files` **array of strings** (optional) A subset list of files that should be unarchived. Mutually exclusive with `folder` and required when `folder` is not present.
* `folder` **string** (optional) The folder which contains all files that should be unarchived. Mutually exclusive with `files` and required when `files` is not present.
* `recurse` **boolean** (optional) If true, unarchive all files in subfolders of `folder`. If false, only unarchive files in `folder`. `folder` must be set. Defaults to `true`.
* `rate` **string** (optional) The speed at which all files in this request are unarchived. Valid entries:
  * For Azure regions, the accepted values are "Standard" and "Expedited". For details about retrieval times, see [Rehydration priority](https://learn.microsoft.com/en-us/azure/storage/blobs/archive-rehydrate-overview#rehydration-priority) in the Azure documentation.
  * For AWS regions, the accepted values are "Standard" and "Bulk". For details about retrieval times, see [Understanding archive retrieval options](https://docs.aws.amazon.com/AmazonS3/latest/userguide/restoring-objects-retrieval-options.html) in the AWS documentation.
* `dryRun` **boolean** (optional) If true, only display the output of the API call without executing the unarchival process. Defaults to `false`.

#### Outputs

* `files` **integer** The number of files to be unarchived.
* `size` **integer** The size of the data, in GB, to be unarchived.
* `cost` **number** The total cost, in millidollars, to be charged for the unarchival request.

#### Errors

* InvalidInput
  * if both `files` and `folder` are provided.
* ResourceNotFound
  * The specified project does not exist.
  * A file or folder does not exist.
* PermissionDenied
  * CONTRIBUTE access required.