Transfer API Menu
  • Transfer API Documentation
  • API Overview
  • Endpoint Activation
  • Task Submission
  • Task Monitoring
  • File Operations
  • Endpoint Management
  • Endpoint Search
  • Endpoint Roles
  • Endpoint Bookmarks
  • Endpoint ACL Management
  • Advanced Endpoint Management
  • Change History
Skip to main content
Globus Docs
  • APIs
    Auth Flows Groups Search Transfer Python SDK Helper Pages
  • How To
  • Guides
    Globus Connect Server High Assurance Collections for Protected Data Command Line Interface Premium Storage Connectors Security Modern Research Data Portal
  • Support
    FAQs Mailing Lists Contact Us Check Support Tickets
  1. Home
  2. Globus APIs
  3. Transfer API Documentation

Endpoint Bookmarks

Table of Contents
  • 1. Overview
  • 2. Document Types
    • 2.1. Bookmark Document
      • 2.1.1. Bookmark Document Fields
  • 3. Path Arguments
  • 4. Common Query Parameters
  • 5. Common Errors
  • 6. Operations
    • 6.1. Get list of bookmarks
    • 6.2. Create bookmark
    • 6.3. Get bookmark by id
    • 6.4. Update bookmark
    • 6.5. Delete bookmark by id

1. Overview

Endpoint bookmarks allow a user to create an alias for an endpoint and path that they frequently use, and give it a custom name. The globus.org website will allows using the bookmark to quickly find commonly used endpoints and paths, and other clients are free to provide this as a convenience to users as well. The CLI also allows direct usage of bookmarks (see the man pages), but the REST API does not support using bookmark names in place of endpoints elsewhere in the API. They are purely provided as a convenience to users.

Bookmarks are always private to the user identity that creates them, and can’t be shared. A bookmark will be visible, editable, and deletable if the identity owning the bookmark is in the set of linked identities associated with the Globus Auth token used to authenticate with the API.

Note

Each user can have at most 100 bookmarks.
Note

If the endpoint pointed to by a bookmark is deleted, the bookmark will continue to exist and show up in bookmark_list results. This is to allow users to see that the deletion happened. Users can manually delete the bookmark once they see what happened.

2. Document Types

2.1. Bookmark Document

The "bookmark" document type represents a named alias for a Globus endpoint and path.

Bookmark Document Example
{
  "DATA_TYPE": "bookmark",
  "id": "1405823f-0597-4a16-b296-46d4f0ae4b15",
  "name": "genomics dataset1",
  "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
  "path": "/projects/genomics/dataset1/"
}

2.1.1. Bookmark Document Fields

Field Name JSON Type Description

DATA_TYPE

string

Always has value "bookmark" to indicate this document type. Optional in create requests.

id

string

Globally unique id string for this bookmark. This is system generated and should not be included in create requests.

name

string

Name of the bookmark, which will be used in searches. Unicode strings, with the following characters disallowed: '\n', '\r'. The name must be unique for each user. Note that spaces and special characters must be url encoded when using the bookmark in the Transfer CLI.

endpoint_id

string

Id of the endpoint to bookmark.

path

string

Path to a directory on the endpoint. Must end in "/".

pinned

boolean

Is the bookmark pinned (a favorite). Default: false

3. Path Arguments

Name Type Description

bookmark_id

string

Unique identifier for a bookmark.

4. Common Query Parameters

Name Type Description

fields

string

Comma separated list of fields to include in the response. This can be used to save bandwidth on large list responses when not all fields are needed.

5. Common Errors

The error code can be found in the HTTP response body JSON document. See error overview .

Code HTTP Status Description

BookmarkNotFound

404

If <bookmark_id> not found

EndpointNotFound

404

If endpoint_id not found when creating a bookmark.

Conflict

409

If a bookmark with the same name owned by the current user already exists.

Exists

409

If a bookmark with the same endpoint_id and path already exists.

LimitExceeded

409

If the user already has the maximum of 100 bookmarks.

ServiceUnavailable

503

If the service is down for maintenance.

6. Operations

6.1. Get list of bookmarks

Get a list of bookmarks created by the current user.

URL

/bookmark_list

Method

GET

Response Body

{

    "DATA_TYPE": "bookmark_list",
    "DATA": [
        {
          "DATA_TYPE": "bookmark",
          "id": "1405823f-0597-4a16-b296-46d4f0ae4b15",
          "name": "genomics dataset1",
          "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
          "path": "/projects/genomics/dataset1/"
        },
        {
          "DATA_TYPE": "bookmark",
          "id": "1405823f-0597-4a16-b296-46d4f0ae4b15",
          "name": "physics dataset7",
          "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
          "path": "/projects/physics/dataset7/"
        }
    ]
}

6.2. Create bookmark

On success returns a copy of the created bookmark with the system generated id added.

Required fields: name, endpoint_id, path.

URL

/bookmark

Method

POST

Request Body

{
  "name": "physics dataset7",
  "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
  "path": "/projects/physics/dataset7/"
}

Response Body

{
  "DATA_TYPE": "bookmark",
  "id": "1405823f-0597-4a16-b296-46d4f0ae4b15",
  "name": "physics dataset7",
  "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
  "path": "/projects/physics/dataset7/"
}

6.3. Get bookmark by id

Get a single bookmark by id.

URL

/bookmark/<bookmark_id>

Method

GET

Response Body

{
  "DATA_TYPE": "bookmark",
  "id": "1405823f-0597-4a16-b296-46d4f0ae4b15",
  "name": "physics dataset7",
  "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
  "path": "/projects/physics/dataset7/"
}

6.4. Update bookmark

On success returns a copy of the updated bookmark. Only the name field can be updated. If other fields are included, they will be ignored, but clients are encouraged to pass only the name.

URL

/bookmark/<bookmark_id>

Method

PUT

Request Body

{
  "name": "physics dataset7"
}

Response Body

{
  "DATA_TYPE": "bookmark",
  "id": "1405823f-0597-4a16-b296-46d4f0ae4b15",
  "name": "physics dataset7",
  "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
  "path": "/projects/physics/dataset7/"
}

6.5. Delete bookmark by id

Delete a single bookmark by id. Returns a result document on success.

URL

/bookmark/<bookmark_id>

Method

DELETE

Response Body

{
    "DATA_TYPE": "result",
    "code": "Deleted",
    "message": "Bookmark 'c67b666f-e1ad-4f67-af2c-48340dd12ada' deleted successfully",
    "resource": "/bookmark/a624df8b",
    "request_id": "ABCdef789"
}
  • Transfer API Documentation
  • API Overview
  • Endpoint Activation
  • Task Submission
  • Task Monitoring
  • File Operations
  • Endpoint Management
  • Endpoint Search
  • Endpoint Roles
  • Endpoint Bookmarks
  • Endpoint ACL Management
  • Advanced Endpoint Management
  • Change History
© 2010- The University of Chicago Legal Privacy Accessibility