API Overview

All the URLs in the Transfer documentation are relative to a base url for the transfer service.

so the full URL to /task_list will be:

Clients should store the base URL in one place and use it when constructing resource URLs, to simplify changing versions.

The API uses json for all input and output, including error documents.

Note that application/x-www-form-urlencoded is not supported. The body should contain the actual JSON data, not a form encoded version of that data.

The json representation uses a "DATA_TYPE" key to specify the type of resource and a "DATA" key containing a list of sub-documents, if any. For example, the endpoint document type is described in detail here:

Authentication to the Transfer API requires using Globus Auth to obtain an access token. The Globus Auth developer guide describes the steps to register a client and request tokens for that client to make requests to Globus services.

When requesting tokens, request Transfer all scope in order to get an access token scoped to make requests to the Transfer API:

Once obtained, the access token needs to be passed to the Transfer API in the Authorization header with the method Bearer:

You can test this by saving the token to a private temporary file, e.g. $HOME/tmp-globus-auth-token.txt, and then passing it to curl with the -H option:

You could also paste the token directly but then it will be stored in your shell history, which is often not desirable.

When an error occurs an HTTP status code >=400 will be returned. The body of the response will be a JSON document with details about the error, including code and message fields. The error code will also be provided in the "X-Transfer-API-Error" header. Note that requests outside the API path version prefix may return an HTML or plaintext error body instead. Here is an example error returned when an endpoint is not found:

A 404 status code is used for this response. The code field has the same value as the X-Transfer-API-Error header, for convenient access.

Activation provides the Transfer service with an x509 credential required by some endpoints so the service can perform operations on behalf of the user on the file system. Generally, only Globus Connect Server v4 and legacy GridFTP endpoints will require activation.

If you are unsure if you need to activate an endpoint, the first step is auto-activation. Auto-activation will succeed if the endpoint already has a cached credential or if it never needed one in the first place. If it fails, it will return an activation requirements document that can be used for an activation request, however it is generally simpler to send users to the Globus Webapp for Web Activation.

Standard Globus Connect Server v5 mapped collections require users to consent to a collection specific dependent data_access scope in order to access data on that collection. Every such scope will be in the format:

Where COLLECTION_UUID is the uuid of a collection that requires the data_access scope. You may request multiple dependent scopes by separating them with spaces:

If you know ahead of time that you will be accessing a mapped collection that requires a data_access dependent scope, you should request those consents when you first request tokens for authenticating with Transfer.

However, if you don’t know ahead of time which endpoints or collections you will be accessing, you can add error handling logic to handle ConsentRequired errors raised when Transfer is unable to get the dependent tokens needed to access data. The body of these error responses will contain a required_scopes field with a list of scopes to which the user must consent in order to complete the failing request.

The convention used for examples in this document is similar to raw HTTP requests and responses, with the URL shortened and most headers omitted. This format is used to provide a quick description of how to make a request, independent of the client used. As an example, to get a task_list for the logged in user, the request is described as:

This means that a GET request must be made to the task_list resource, which actually has the URL https://transfer.api.globusonline.org/v0.10/task_list for version v0.10. This is BASE_URL + /task_list. As discussed above, the BASE_URL should be set in one place and reused, not hard coded into each request. The actual raw HTTP request will typically include many headers:

Most of these headers were added by the browser (Firefox); the developer will not normally need to deal with them.

For examples that involve sending data, the body is included inline, just like it would be in an HTTP request. For example endpoint creation is described like this:

This means that to create an endpoint, a request using method POST can be made to BASE_URL + /endpoint, with header content-type set to "application/json", and having as the request body the JSON data describing the endpoint. Other headers are required for authentication, but they are not specific to this request.

To create a directory on an endpoint, submit a mkdir document to POST /operation/endpoint/ID/mkdir

If the path field does not contain an absolute path, it’s assumed to be relative to the user’s home directory (~).

A standard error document is returned on failure; on success a "mkdir_result" is returned, with status 202 and code DirectoryCreated:

Note that recursive transfers implicitly create directories as needed at the destination; the purpose of the mkdir resource is to provide explicit creation.

A transfer is a request to copy files and directories from a source endpoint to a destination endpoint. The request document is essentially a list of transfer items containing source / destination path pairs.

To fulfill the request, the service creates a task, which can be monitored using the task_id.

For directory transfer items, the contents of the source directory are recursively copied to the destination directory, including any subdirectories. Any intermediate/parent directories that don’t exist on the destination will be created.

For file transfer items, the source file is copied to the file path specified as the destination. The destination path can’t be a directory, This is to avoid inconsistent behavior depending on whether or not the destination exists, so when run repeatedly (for example to keep two copies in sync) it performs the same operation each time.

Both endpoints need to be activated before the transfer is submitted. If an endpoint expires before the transfer is complete, the endpoints can be re-activated to allow it to continue, up until the deadline (which defaults to 24 hours after the request time).

When submitting a transfer, you must first get a submission_id:

The submission id should be saved in case the submission is interrupted before a result is received from the server. The transfer can then be resubmitted, and if the original request was successful it will not double submit, it will simply return a result indicating that it’s a duplicate id, with the id of the task created to fulfill the request.

The transfer itself is submitted via POST /transfer:

and returns a transfer_result:

sync_level can be used to request that only modified files are transferred, using different mechanisms to determine modification. See the transfer document type for details on the different sync levels. If sync_level is not included or null, all files will be transferred.

To track the progress of a newly submitted task, use the task_id field of the returned result document.

This returns a task document.

A request to cancel the task can be submitted like this:

It is possible that the transfer will finish before the cancellation goes through; a result document type is returned with a message describing what happened.

Remote files and directories can be deleted on an endpoint by submitting a delete document to POST /delete:

The submission_id, label, and deadline fields behave just like the same fields in a transfer document, and the delete_result returned after submission is the same as a transfer_result.

If any of the paths point to a directory, recursive must be set to true and the entire directory contents will be deleted. Deleting a directory only if it is empty is not supported.

If ignore_missing is not set, the job will fail and stop deleting paths if one of the paths does not exist.

To avoid breaking backward compatibility in 0.10, delete tasks are not included by default in task_list. To include delete tasks, use filter=type:TRANSFER,DELETE.

The Transfer service uses multiple types of paging for controlling results depending on the resource used. Resource documentation will specify which type of paging that resource uses.

Only certain fields support filtering; see the reference documentation for a full list. There are several types of filters, including date range, a single value, or a list of values. See the field documentation for descriptions and examples.

This example for the task list returns ACTIVE and SUCCESSFUL tasks submitted before December 20 2010:

The new convention for filters is to use separate parameters for each, of the form filter_NAME - see Endpoint Search for an example.

The orderby parameter sets a sort field and direction. Only fields which support filtering are sortable. The value is a comma separated list of field names, with an optional direction specifier. For example:

returns tasks first ordered by status, in ascending alphabetical order, then within tasks with the same status sorts by request_time, with newer tasks first (descending).

The fields query parameter can be used to limit which fields are included in the response, for example:

will return a task list with only task_id and status fields in each task. This can save bandwidth and parsing time if you know you only need certain fields.

Field selection can also be done on sub-documents, by prefixing the field name with the document type name. For example:

will include only the id and display_name of each endpoint.