Data Asset

Prerequisites

• Generated Access Token with Datasets scope

• The Data Asset's ID

You can find Data Asset's ID below the title.

Data Asset Object

• created float64

  Data Asset creation time.

• description string

  Data Asset description.

• field string

  Field of research.

• id integer

  Metadata id.

• last_transferred integer

  Time Data Asset's files were last transferred to a different S3 storage location.

• last_used integer

  Time Data Asset was last used in seconds from unix epoch.

• mount string

  The default mount folder of the Data Asset.

• name string

  Name of the Data Asset.

• owner string Data Asset owner's ID.

• owner_email Data Asset owner's email address.

• size string

  Size in bytes of the Data Asset.

• state enum

  Data Asset creation state.

  • draft

    Data Asset is still being created.

  • ready

    Data Asset is ready to use.

  • failed

    Data Asset creation failed.

• source_bucket

  Information regarding the bucket from which the Data Asset was created.

  • bucket string

    The original buckets name

  • origin enum

    • aws

    • local

    • gcp

  • prefix string

    The folder in the s3 bucket from which the Data Asset would be created.

• tags list<string>

  Keywords for searching the Data Asset by.

• transfer_error

  The error that occurred during the last transfer attempt if it failed.

• type enum

  Type of the Data Asset.

  • dataset

  • result

  • combined

  • model

• app_parameters list The name and value of app panel parameters used to generate the result Data Asset.

• contained_data_assets list

  List of structs containing information about the contained Data Assets, if the Data Asset is of type combined.

• custom_metadata dictionary

  According to custom metadata fields defined by deployment admin and values that were set by the user.

• nextflow_profile string Pipeline Nextflow profile used to generate the result Data Asset.

• provenance dictionary

  Shows the Data Asset provenance if type is result.

  • commit

    Commit hash of the Capsule or Pipeline used to generate the result.

  • run_script

    Run script of the Capsule or Pipeline computation that generated the result.

  • data_assets

    Data Assets attached to the Capsule or Pipeline when the result was generated.

  • docker_image

    Docker image used to create the Data Asset.

  • capsule

    Capsule used to create the Data Asset.

  • computation Computation that generated the result.

Create Data Asset

POST https://{codeocean-domain}/api/v1/data_assets

This API allows for the creation of Data Assets from either an S3 bucket or the results of a computation.

Admins and Capsule/Pipeline owners can create a Data Asset from another user's run.

Prerequisite

Before using this API call, you may require AWS Cloud Credentials configured as Secrets or an Assumable Role. You can find more information about managing secrets here.

Request Body

Name	Type/Values	Description
name*	string	Data Asset name.
description	string	Data Asset description.
mount*	string	Data Asset default mount folder.
tags*	list/string	Keywords applied to the Data Asset to aid in searching.
custom_metadata	string custom field - string number custom field - number date custom field - number (unix epoch format timestamp in seconds)	Map of key value pairs, according to custom metadata fields defined by the admin.
source*	struct - aws , computation , or cloud_workstation
aws*
endpoint_name	string	Provide name of the custom S3 endpoint where the bucket is stored.
bucket*	string	The S3 bucket from which the Data Asset would be created.
prefix*	path	The folder in the S3 bucket from which the Data Asset would be crated.
keep_on_external_storage*	boolean	When set to true, the Data Asset files will not be copied to Code Ocean.
public*	boolean	When set to true, Code Ocean will try to access the source bucket without credentials.
use_input_bucket	boolean	When set to true, Code Ocean will try to create the Data Asset from an internal input bucket. Only allowed to Admin users. All aws properties ignored except prefix.
computation
id	string	Computation ID.
path	path	Results path. Leave empty to capture all result files.
cloud_workstation
id	string	Computation ID.
path	string	Capsule path (must not be empty).
run_script	string	Path to the script that was executed relative to the /Capsule folder. Existence determines if the data would be of type result in cases when it was not the default code/run.
target	struct	Optional for designating an S3 storage location outside of Code Ocean. Only applicable for source type of computation.
aws
endpoint_name	string	Optional to provide name of the custom S3 endpoint where the bucket is stored.
bucket	string	The S3 bucket in which the Data Asset would be created.
prefix	path	The folder in the S3 bucket in which the Data Asset would be created
results_info	struct	When the source of the data is a result in an S3 bucket originating from an exported Capsule/Pipeline, additional information can be provided to populate lineage & provenance.
capsule/pipeline_id	string	The ID of the Capsule or Pipeline that was executed. Must be provided when using results_info.
version	integer	Capsule or Pipeline Release version.
commit	string	Commit hash of Capsule/Pipeline code at time of execution.
run_script	string	Path to the script that was executed relative to the /Capsule folder in cases when it was not the default code/run.
data_assets	array<string>	IDs of Data Assets used during the run.
parameters	array<dictionary>	Run Parameters.
name	string	Parameter label.
param_name	string	Parameter name.
value	string	Parameter value.
nextflow_profile	string	Pipeline Nextflow Profile
processes	array	Pipeline processes' information.
name	string	Pipeline process name as it appears in the main.nf script.
capsule_id	string	The ID of the Capsule executed in the process.
version	integer	Release Capsule version.
public	boolean	When set to true, indicates the Capsule is a public Code Ocean App.
parameters	array<string>	Run parameters.
name	string	Parameter title.
param_name	string	Parameter name.
value	string	Parameter value.

Scope

Type	Permission
Data Asset	Read & Write

Create a Data Asset from a Public S3 Bucket

Request Example Bash

curl -X POST https://{codeocean-domain}/api/v1/data_assets \
   -u 'cop_d23dasd312': \
   -H 'Content-Type: application/json' \
   --data-raw '{
      "name": "import public AWS bucket with dataset api",
      "description": "meaningful-c",
      "mount": "citations",
      "tags": ["Genomics"],
      "source": {
         "aws": {
             "public": true,
             "bucket": "codeocean-public-data",
             "prefix": "example_datasets/ATAC/hg38_2bit/"
         }
      }
   }'

Request Example Python SDK

from codeocean.data_asset import DataAssetParams, Source, AWSS3Source

data_asset_params = DataAssetParams(
    name="Dataset From Bucket",
    description="S3 bucket import",
    mount="my-data",
    tags=["my", "data"],
    source=Source(
        aws=AWSS3Source(
            bucket="codeocean-public-data",
            prefix="example_datasets/ATAC/hg38_2bit/",
            public="true",
        ),
    ),
)

data_asset = client.data_assets.create_data_asset(data_asset_params)

Create a Data Asset from a Private S3 Bucket

Request Example Bash

curl -X POST https://{codeocean-domain}/api/v1/data_assets \
   -u 'cop_d23dasd312': \
   -H 'Content-Type: application/json' \
   --data-raw '{
      "name":"import private AWS bucket with Data Asset API",
      "description":"meaningful-c",
      "mount":"citations",
      "tags":["Genomics"],
      "source":
         {
         "aws":
                 {
                  "bucket":"codeocean-private-data",
                  "prefix":"example_datasets/ATAC/hg38_2bit/"
                 }
         }
}'

Request Example Python SDK

from codeocean.data_asset import DataAssetParams, Source, AWSS3Source

data_asset_params = DataAssetParams(
    name="Dataset From Bucket",
    description="S3 bucket import",
    mount="my-data",
    tags=["my", "data"],
    source=Source(
        aws=AWSS3Source(
            bucket="codeocean-private-data",
            prefix="example_datasets/ATAC/hg38_2bit/",
        ),
    ),
)

data_asset = client.data_assets.create_data_asset(data_asset_params)

Create an External Result Data Asset

Request Example Bash

curl -X POST https://{codeocean-domain}/api/v1/data_assets
   -H 'Content-Type: application/json' \
   -u 'cop_d23dasd312': \
   --data-raw '{
       "name": "RNA-Sequencing",
       "description": "these are reads from an experiment", 
       "mount": "Reads",
       "tags": ["Genomics", "RNA"],
       "source": 
         {
         "computation": 
                 {
                         "id":”8f174aed-64ce-43eb-9c16-64d25da84bda”,
                         “path”:”Alignment/” (Alignment is a folder in Results)
                 }
},
      “target”:
         {
         “aws”:
                 {
                         “bucket”:”my-bucket”,
                         “prefix”:”deposit/my/results/”
                 }
         }
}'

Request Example Python SDK

from codeocean.data_asset import (
        DataAssetParams, 
        Source,
        ComputationSource, 
        Target,
        AWSS3Target
        )
        
data_asset_params = DataAssetParams(
    name="RNA-Sequencing",
    description="these are reads from an experiment",
    mount="Reads",
    tags=["Genomics", "RNA"],
    source=Source(
        computation=ComputationSource(
            id="8f174aed-64ce-43eb-9c16-64d25da84bda",
            path="Alignment/"
        ),
    ),
    target=Target(
        aws=AWSS3Target(
            bucket="my-bucket",
            prefix="deposit/my/results/"
        )
    )
    
data_asset = client.data_assets.create_data_asset(data_asset_params)

Create a Result Data Asset

Request Example Bash

curl -X POST https://{codeocean-domain}/api/v1/data_assets \
-H 'Content-Type: application/json' \
-u 'cop_d23dasd312': \ 
   --data-raw '{
       "name": "Data asset From API",
       "description": "An example for creating data asset from CO API",
       "mount": "some-folder",
       "tags": [ "keyword1", "keyword2" ],
       "source": {
         "computation": {
          "id": "8f174aed-64ce-43eb-9c16-64d25da84bda"
       }
    }
}'

Request Example Python SDK

from codeocean.data_asset import (
        DataAssetParams, 
        Source,
        ComputationSource
        )
        
data_asset_params = DataAssetParams(
    name="RNA-Sequencing",
    description="these are reads from an experiment",
    mount="Reads",
    tags=["Genomics", "RNA"],
    source=Source(
        computation=ComputationSource(
            id="8f174aed-64ce-43eb-9c16-64d25da84bda",
            path="Alignment/"
        ),
    )
)
    
data_asset = client.data_assets.create_data_asset(data_asset_params)

Create a Result Data Asset from External Result

Request Example Bash

curl -X POST https://codeocean.[my-domain].com/api/v1/data_assets \
   -u "cop_YTM2OGRlO": \
   -H 'Content-Type: application/json' \
   --data-raw '{
      "name": "Test the New API",
      "description": "meaningful-c",
      "mount": "citations",
      "tags": ["Genomics"],
      "source": {
         "aws": {
             "public": true,
             "bucket": "codeocean-public-data",
             "prefix": "unit_test/Images/"
         }
      },
      "results_info": {
         "capsule_id": "8398ed85-f61f-4e58-aead-82759c238f99",
         "run_script":"code/run",
         "data_assets":[
                "76630c77-8293-4442-9b26-3eb8f7292940",
                "de855853-8aed-4262-8072-a9c1e9ea1a6c"
         ],
         "parameters":[
                {
                        "name":"Number of Threads",
                        "value":"1"
                }
         ]
        }
   }'

Request Example Python SDK - Capsule

from codeocean.data_asset import (
    DataAssetParams,
    Source,
    AWSS3Source,
    ResultsInfo,
    Param
)

data_asset_params = DataAssetParams(
        name="Dataset From External Computation",
        description="This Data Asset was imported from Outside",
        mount="Results",
        tags=["SDK"],
        source=Source(
            aws=AWSS3Source(
                bucket="codeocean-public-data",
                prefix=f"unit_test/Reads/",
                public=True,
                keep_on_external_storage=False
                )
            )
        ),
        results_info=ResultsInfo(
              capsule_id='8398ed85-f61f-4e58-aead-82759c238f99',
              version='1',
              commit='123',
              run_script='code/run',
              data_assets=[
                  "76630c77-8293-4442-9b26-3eb8f7292940",
                  "de855853-8aed-4262-8072-a9c1e9ea1a6c"
                ],
              # Ordered Parameters 
              parameters=Param(
                  name='Number of Threads',
                  value='1'
                  )
              # Named Parameters
              parameters=Param(
                  param_name='Number of Threads',
                  value='1'
              )
            

Request Example Python SDK - Pipeline

from codeocean.data_asset import (
    DataAssetParams,
    Source,
    AWSS3Source,
    ResultsInfo,
    Param
)

data_asset_params = DataAssetParams(
        name="Dataset From External Computation",
        description="This Data Asset was imported from Outside",
        mount="Results",
        tags=["SDK"],
        source=Source(
            aws=AWSS3Source(
                bucket="codeocean-public-data",
                prefix=f"unit_test/Reads/",
                public=True,
                keep_on_external_storage=False
                )
            )
        ),
        results_info=ResultsInfo(
              pipeline_id='8398ed85-f61f-4e58-aead-82759c238f99',
              version='1',
              data_assets=[
                  "76630c77-8293-4442-9b26-3eb8f7292940",
                  "de855853-8aed-4262-8072-a9c1e9ea1a6c"
                ],
              processes=PipelineProcess(
                  name='FastQC',
                  capsule_id='8398ed85-f61f-4e58-aead-82759c238f99'
                  version='1',
                  public=False,
                  # Ordered Parameters
                  parameters=Param(
                      name='Number of Threads',
                      value='1'
                  )
                  # Named Parameters
                  parameters=Param(
                      param_name='Number of Threads',
                      value='1'
              )
            

Create a Combined Data Asset

Request Example Bash

curl -X POST https://codeocean.[my-domain].com/api/v1/data_assets \
   -u "cop_YTM2OGRlO": \
   -H 'Content-Type: application/json' \
   --data-raw '{
      "name": "My Combined Assets",
      "description": "Create a Combined Data Asset",
      "mount": "Reads",
      "tags": ["Genomics"],
      "data_asset_ids":[
            '75fe2606-f414-469a-a309-b7d74f169885',
            '10bc2606-d321-987z-d365-c7c12a989235
            ]
         }'

Request Example Python SDK

from codeocean.data_asset import (
        DataAssetParams
        )
        
data_asset_params = DataAssetParams(
    name="My Combined Assets",
    description="Create a Combined Data Asset",
    mount="Reads",
    tags=["Genomics"],
    data_asset_ids=[
            '75fe2606-f414-469a-a309-b7d74f169885',
            '10bc2606-d321-987z-d365-c7c12a989235'
            ]
        )
    
data_asset = client.data_assets.create_data_asset(data_asset_params)

Create a Data Asset with Custom Metadata Tags

Request Example Bash

curl -X POST https://{codeocean-domain}/api/v1/data_assets
   -H 'Content-Type: application/json' \
   -u 'cop_d23dasd312': \ 
   --data-raw '{
       "name": "myDatasetFromPublic",
       "description": "a descriptive description",
       "mount": "Mymount",
       "tags": ["t1", "t2"],
       "custom_metadata":
         {
                 "some_field": "one", 
                 "another_field": 1, 
                 "dateField": 1676246400 
        }, 
       "source": 
         {
         "computation": 
                 {
                   "id":”computation_ID”,
                   "path": "/path/to/folder/" (remove if want all Results)
                 }
         }
}'

Request Example Python SDK

from codeocean.data_asset import (
        DataAssetParams, 
        Source,
        ComputationSource
        )
        
data_asset_params = DataAssetParams(
    name="RNA-Sequencing",
    description="these are reads from an experiment",
    mount="Reads",
    tags=["Genomics", "RNA"],
    custom_metadata={"Project": "Bulk RNA", "Medallion": "Bronze"},
    source=Source(
        computation=ComputationSource(
            id="8f174aed-64ce-43eb-9c16-64d25da84bda",
            path="Alignment/"
        ),
    )
)
    
data_asset = client.data_assets.create_data_asset(data_asset_params)

Response

Data Asset Object.

The API only returns a confirmation of the validity of the creation request, not the success of the creation, since the creation takes time. Poll on the dataset details and monitor its state until it’s ready.

Get Data Asset

GET https://{codeocean-domain}/api/v1/data_assets/{data_asset_id}

This API retrieves metadata for your Data Asset.

Path Parameters

Name	Type
data_asset_id *	string

Scope

Type	Permission
Data Asset	Read & Write

Request Example Bash

curl https://{codeocean-domain}/api/v1/data_assets/4bc97533-6eb4-48ac-966f-648548a756d2 \
   -u 'cop_d23dasd312':

Request Example Python SDK

data_asset = client.data_assets.get_data_asset(data_asset_id="4bc97533-6eb4-48ac-966f-648548a756d2")

Update Metadata

PUT https://{codeocean-domain}/api/v1/data_assets/{data_asset_id}

This API allows for the updating of a Data Asset's metadata.

Path Parameters

Name	Type
data_asset_id*	string

Request Body

Name	Type
name*	string
description*	string
tags*	string
mount*	string
custom_metadata	dictionary

Scope

Type	Permission
Data Asset	Write

Request Example Bash

curl -X PUT https://{codeocean-domain}/api/v1/data_assets/d36665a7-ef59-4b8e-a799-bee7f83ee317 \
   -H 'Content-Type: application/json' \
   -u 'cop_d23dasd312': \
   --data-raw '{
        "name": "Modified The Name",
        "description": "a new description from the API!",
        "tags": ["I","Am","New"],
        "mount": "NewMount"
}'

Request Example Python SDK

from codeocean.data_asset import DataAssetUpdateParams

data_asset_params = DataAssetUpdateParams(
    name="Modified The Name",
    description="a new description from the SDK!",
    tags=["I","Am","New"],
    mount="NewMount",
)

data_asset = client.data_assets.update_metadata(
    dataset_id="4bc97533-6eb4-48ac-966f-648548a756d2",
    update_params=data_asset_params,
)

Response

Data Asset Object

Archiving/Unarchiving a Dataset

PATCH https://{codeocean-domain}/api/v1/data_assets/{data_asset_id}/archive?archive={true|false}

This API allows for the archiving and retrieval of your Data Asset.

Path Parameters

Name	Type
data_asset_id*	string

Query Parameters

Name	Type
archive*	boolean

Scope

Type	Permission
Data Asset	Read & Write

Request Example Bash

Archiving a Dataset

curl -X PATCH https://{codeocean-domain}/api/v1/data_assets/e25ec103-a712-4882-a9fa-3cd5a80438a8/archive?archive=true
   -u 'cop_d23dasd312': 

Unarchiving a Dataset


curl -X PATCH https://{codeocean-domain}/api/v1/data_assets/e25ec103-a712-4882-a9fa-3cd5a80438a8/archive?archive=false
   -u 'cop_d23dasd312':

Request Example Python SDK

client.data_assets.archive_data_asset(
    data_asset_id="edf1a1df-4e97-4888-9e2a-92bf70e341e8",
    archive=True,
)

Search Data Assets

POST https://{codeocean-domain}/api/v1/data_assets/search

This API allows for the searching of Data Assets in your deployment.

Request Body (all fields optional)

Name	Type or Value	Description
offset	int	Specifies the starting index for the search.
limit	int	Specifies how many items to return (up to 1000, defaults to 100).
next_token	string	Represents the token for the next page of results as provided in the previous response. If both from and next_token are set, the from parameter is ignored.
sort_order	asc, desc	Determines the result sort order. Must be provided with sort_field, otherwise ignored.
sort_field	created, type, name, size	Determines the field to sort by (default created).
query	string	Determines the search query. Can be a free text or in the form of “name:... tag:... run_script:... commit_id:...”.
type	dataset, result, combined, or model	Specifies the type of Data Asset to include in the response. If omitted results may include all types.
ownership	created, shared	Search Data Asset by ownership. created - Only Data Assets created by the user. shared - Data Assets shared with the user. ** Defaults to all accessible, and admins will have access to all Data Assets in the system.
origin	internal, external	Designates whether to return only internal/external Data Assets.
favorite	boolean	Search only favorite Data Assets.
archived	boolean	Search only archived Data Assets.
filters	list
key	string	Field key can be each of name, description, tags, any custom field key defined by the admin.
value		Field value to be included/excluded (optional).
values		Field values in case of multiple values (optional).
range		Field range to be included/excluded (only one of min/max must be set).
min	number
max	number
exclude	boolean	Whether to include/exclude the field value.

Response

Name	Type	Description
has_more	boolean	Indicates if there are more results.
next_token	number	Specifies the next page token for the next request.
results	array	Array of Data Assets found.

Request Example Bash

curl -X POST https://{codeocean-domain}/api/v1/data_assets/search
   -u 'cop_d23dasd312': \
   -H 'Content-Type: application/json' \
   --data-raw '{
        "offset": 0,
        "limit": 10,
        "sort_order": "desc",
        "sort_field": "name",
        "type": "dataset",
        "ownership": "created",
        "favorite": false,
        "archived": false,
        "query": "tag:bioinforma name:Saccro"
}'

Request Example Python SDK

from codeocean.data_asset import DataAssetSearchParams

data_asset_params = DataAssetSearchParams(
    offset=0,
    limit=10,
    sort_order="desc",
    sort_field="name",
    type="dataset",
    ownership="created",
    archived=False,
    favorite=False,
    query="tag:bioinforma"
)

data_assets = client.data_assets.search_data_assets(data_asset_params)

Request Example Python SDK - Search with Custom Metadata Filter

from codeocean.components import SearchFilter
from codeocean.data_asset import DataAssetSearchParams

data_asset_params = DataAssetSearchParams(
    offset=0,
    limit=100,
    sort_order="desc",
    sort_field="name",
    archived=False,
    favorite=False,
    query="",
    filters=[
        SearchFilter(
            key="experiment type",
            value="MRI"
        ), 
        SearchFilter(
            key="subject id",
            value="12345"
        )
    ]
)

data_asset_search_results = client.data_assets.search_data_assets(data_asset_params)

Request Example Python SDK - Search for >1000 Data Assets

from codeocean.data_asset import DataAssetSearchParams

data_asset_params = DataAssetSearchParams(
    offset=0,
    limit=1000,
    sort_order="desc",
    sort_field="name",
    archived=False,
    favorite=False
)

data_assets = client.data_assets.search_data_assets_iterator(data_asset_params)

The search_data_assets_iterator function iteratively calls the search_data_assets function to return a list of all the Data Assets that match the data_asset_params query. The limit parameter is the page size, i.e. the number of Data Assets to return on each iteration, and as such setting it to 1000 provides the best performance.

Response

{

'has_more': True/False, (indicates whether there are more results)

'next_token': 'sometoken',

'results': [Data Asset Object]

}

Update Permissions of a Data Asset

POST https://{codeocean-domain}/api/v1/data_assets/{data_asset_id}/permissions

This API allows for the updating of a Data Asset's user access permissions in your deployment.

Path Parameters

Name	Type
data_asset_id*	string

Request Body

Name	Type
users*	array<dict>
groups*	array<dict>
everyone*	string
share_assets	bool

Request Example Bash

curl -X POST https://{codeocean-domain}/api/v1/data_assets/{data_asset_id}/permissions \
  -u 'cop_d23dasd312': \
  -H 'Content-Type: application/json' \
  --data-raw '{
       "users": [{"email": "[e-mail]", "role":"owner"}]
       "groups": [{"group":"ad-group","role":"viewer"}],
       "everyone": "viewer",
       "share_assets": "true"
  }'

Request Example Python SDK

from codeocean.data_asset import (
    Permissions
)
                
from codeocean.components import (
    UserPermissions,
    EveryoneRole,
    UserRole,
)
                
update_permissions = Permissions(
    users=[
        UserPermissions(
            email="[e-mail]",
            role=UserRole(value="owner"),
        ),
    ],
    everyone=EveryoneRole(value="viewer"),
    share_assets=True,
)    

client.data_assets.update_permissions(
    data_asset_id="e25ec103-a712-4882-a9fa-3cd5a80438a8",
    permissions=update_permissions,
)

Delete Data Asset

DELETE https://{codeocean-domain}/api/v1/data_assets/{data_asset_id}

This API deletes a Data Asset.

Path Parameters

Name	Type
data_asset_id *	string

Scope

Type	Permission
Data Asset	Read & Write

Request Example Bash

curl DELETE https://{codeocean-domain}/api/v1/data_assets/4bc97533-6eb4-48ac-966f-648548a756d2 \
   -u 'cop_d23dasd312':

Request Example Python SDK

data_asset = client.data_assets.delete_data_asset(dataset_id="4bc97533-6eb4-48ac-966f-648548a756d2")

Transfer Data Asset

POST https://{codeocean-domain}/api/v1/data_assets/{data_asset_id}/transfer

This is an Admin only API that allows transferring a Data Asset's files to a different S3 storage location. This can be used to convert an Internal Data Asset to External, or to change the storage location of an External Data Asset. When applied to Result Data Assets, provenance information is maintained.

When transferring files from an External Data Asset linked to a public S3 bucket, the S3 bucket should have ACLs disabled as described here.

Path Parameters

Name	Type	Description
target*	struct	Struct defining target storage location.
aws*
bucket*	string	The S3 bucket the Data Asset's files will be transferred into.
prefix*	string	The folder in the S3 bucket in which the Data Asset files will be placed.
force	boolean	Perform the transfer even if there are Release Pipelines using it.

Request Body

Name	Type
data_asset_id *	string

Changing the storage location of a Data Asset will break a Pipeline it's used in due to how the Data Asset is referenced in the main.nf file. As such, the force field must be used when transferring a Data Asset used by a Release Pipeline and the Release Pipeline must then be updated.

Request Example Bash

curl -X POST 'http://{codeocean-domain}/api/v1/data_assets/{data_asset_id}/transfer' \
-u "cop_d23dasd312": \
-H 'Content-Type: application/json' \
--data-raw '{
  "target": {
    "aws": {
      "bucket": "MY_BUCKET",
      "prefix": "PREFIX"
    }
  }
}'

Request Example Python SDK

from codeocean.data_asset import TransferDataParams, Target, AWSS3Target

transfer_data_params = TransferDataParams(
    target=Target(
        aws=AWSS3Target(
            bucket="MY_BUCKET",
            prefix="prefix/"
        )
    ),
    force=True
)

client.data_assets.transfer_data_asset(
    data_asset_id=data_asset_id,
    transfer_params=transfer_data_params
)

List Data Asset Files

POST https://{codeocean-domain}/api/v1/data_assets/{data_asset_id}/files

This API allows for listing of an Internal Data Asset's files.

To list files in an External Data Asset, interact with the S3 bucket directly using e.g. the AWS CLI. S3 information can be obtained from the source_bucket field of the get data asset API.

Path Parameters

Name	Type
data_asset_id*	string

Request Body

Name	Type	Description
path	string	The path of a folder within the Data Asset. Empty path will retrieve a list of all files or folders at the root level.

Scope

Type	Permission
Data Asset	Read

Request Example Bash

curl -H "Content-Type: application/json" -u ${CUSTOM_KEY}: -X POST https://${co_domain}/api/v1/data_assets/${data_asset_id}/files --data-raw '{"path": "subfolder"}'

Request Example Python SDK

file_paths = client.data_assets.list_data_asset_files(
    data_asset_id=data_asset_id,
    path="subfolder",
)

Response

{
    "items":[
        {
            "name":"data.txt",
            "path":"subfolder/data.txt",
            "size":77177296,
            "type":"file"
        }
    ]
}

Get Data Asset File URLs

GET https://{codeocean-domain}/api/v1/data_assets/{data_asset_id}/files/urls?path={path_to_file}

This API allows for the generation of two URLs to a file in an Internal Data Asset:

• download_url - Signed URL for downloading the file.

• view_url - Signed URL for viewing the file in the browser.

This API was introduced in Code Ocean version 4.0. The previous Get Data Asset File Download URL API is deprecated but will be supported until August 2026.

Path Parameters

Name	Type
data_asset_id*	string
path_to_file*	string

Scope

Type	Permission
Data Asset	Read

Request Example Bash

curl -H "Content-Type: application/json" -u ${CUSTOM_KEY}: -X GET https://${co_domain}/api/v1/data_assets/${data_asset_id}/files/urls?path=${path_to_file}

Request Example Python SDK

url = client.data_assets.get_data_asset_file_urls(
    data_asset_id=data_asset_id,
    path=file_paths.items[2].name,
)

Response

• download_url string Download file URL

• view_url string View file URL