The Open API specification for Synapse is now available for download!

Download Open API Spec

Access Approval Services

The Access Approval services manage the fulfillment of Access Requirements, on a per-user basis. (See Access Requirement Services for more information.) Most of the Access Approval services are available only to members of the Synapse Access and Compliance Team (ACT).

Web Services
Resource Description
POST /accessApproval Create an Access Approval, thereby fulfilling an Access Requirement for a given user. Self-signed Access Approvals may be generated by the user being …
GET /accessApproval/{approvalId} Retrieving an AccessApproval given its ID.
POST /accessApproval/group Retrieving a page of AccessorGroup. This service is only available for ACT. ACT can filter on AccessRequirementId, submitterId, accessorId and expired…
POST /accessApproval/notifications Fetches the notifications sent for an access requirement and a list of recipients. This service is only available for ACT.
PUT /accessApproval/group/revoke Revoke a group of accessors. Only ACT can perform this action.
POST /accessApproval/information Retrieve a batch of AccessApprovalInfo for a single user.
DELETE /accessApproval Revoke all Access Approvals an accessor may have for a given Access Requirement. The caller must match the accessorId or the caller must be a member o…
POST /accessApproval/search Search through the history of access approvals filtering by accessor/submitter and optional by access requirement id. The caller must be a member of t…

Access Requirement Services

These services manage the Access Requirements/Restrictions (ARs) which may be placed on Entities, or Teams. An Access Requirement specifies the type of access being restricted as well as how the requirement is fulfilled.

ARs complement Access Control Lists (ACLs) for managing access to Synapse objects. While ACLs are managed by entity owners, ARs are managed by the Synapse Access and Compliance Team (ACT), which is responsible for governance of sensitive data. Before one may access data associated with an AR, there must be a corresponding Access Approval. For certain ARs -- of the "self-sign" variety -- one may grant ones own approval by agreeing to associated 'terms of use.' For other Access Requirements -- of the 'ACT' variety -- approval may be granted only by the ACT.

As stated above, an AR specifies the type of access being controlled. Generally entities are restricted with DOWNLOAD access. A Synapse user may be able to see that a Synapse File exists, but be unable to download the content due to such an AR. Teams are restricted using the PARTICIPATE access type: Prior to joining a Team a user must fulfill any associated ARs controlling this type of access.

Entity ARs are inherited from ancestors. E.g. an AR applied to a Folder will control all Files in the Folder, or within sub-folders of the Folder. Access Requirements are cumulative: A File will be controlled both by ARs applied to it directly and by ARs applied to any and all of its ancestors.

Access Requirements are fulfilled on a per-user basis using the Access Approval Services.

Web Services
Resource Description
POST /accessRequirement Add an Access Requirement to an Entity, or Team. This service may only be used by the Synapse Access and Compliance Team.
GET /accessRequirement/{requirementId} Get an Access Requirement to an Entity, or Team based on its ID.
PUT /accessRequirement/{requirementId} Modify an existing Access Requirement. This service may only be used by the Synapse Access and Compliance Team.
POST /entity/{id}/lockAccessRequirement Add a temporary access restriction that prevents access pending review by the Synapse Access and Compliance Team. This service may be used only by an …
GET /entity/{id}/accessRequirement Retrieve paginated list of ALL Access Requirements associated with an entity.
GET /team/{id}/accessRequirement Retrieve paginated list of ALL Access Requirements associated with a Team.
DELETE /accessRequirement/{requirementId} Delete an Access Requirement. This service may only be used by the Synapse Access and Compliance Team.
PUT /accessRequirement/conversion Convert an ACTAccessRequirement to a ManagedACTAccessRequirement. Only ACT member can perform this action.
GET /accessRequirement/{requirementId}/subjects Retrieve a page of subjects for a given Access Requirement ID.
GET /accessRequirement/{requirementId}/acl Fetch the ACL for the access requirement with the given id.
POST /accessRequirement/{requirementId}/acl Assign the given ACL to the access requirement with the given id. Only an ACT member is allowed to assign the ACL. Only supports {@link ACCESS_TYPE#RE…
PUT /accessRequirement/{requirementId}/acl Updates the ACL for the access requirement with the given id. Only an ACT member is allowed to update the ACL. Only supports {@link ACCESS_TYPE#REVIEW…
DELETE /accessRequirement/{requirementId}/acl Delete the ACL for the access requirement with the given id. Only an ACT member is allowed to delete the ACL.
POST /accessRequirement/search Performs a search through the available access requirements matching the criteria in the given request

Activity Services

The Activity model represents the main record of Provenance in Synapse. It is analygous to the Activity defined in the W3C Specification on Provenance.

Used & Generated By

Used links are stored directly in the Activity model object as an array of Used objects. There is a flag in Used that marks if it was "executed". Used is an interface that is implemented by two objects:

  • UsedEntity - For referencing Entities already stored in Synapse
  • UsedURL - For referencing URL-accessed resources stored outside of Synapse. In Provenance visualizations, some URLs are given a special icon, such as links to GitHub. Note: it is also possible to wrap a URL with a FileEntity if you want all the resources that come with Synapse entities.

wasGeneratedBy links are stored for each version of each Entity. Thus you update the entity with the activity id that generated it. You can ask the entity service which activity generated it, and conversely you can ask the activity service what entity versions were generatedBy a given activity.

Access Control for Activities

Access to Activity objects is dictated by the following rules:

  • READ - Granted to those users who can see a single Entity that was generated by this Activity.
  • UPDATE/DELETE - You must be the creator of the Activity to modify or delete it.
  • Setting generatedBy for an Entity (see POST /entity) - You must be the creator of the activity to connect it to an Entity. (The Entity services allow you to specify an activityId that creates a generatedBy relationship between an Activity and an Entity.)

Web Services
Resource Description
POST /activity Create a new Activity. If the passed Activity object contains a Used array, you must set the concreteType field of each Used subclass. Access Control:…
GET /activity/{id} Get an existing Activity Access Control: Granted to those users who can see a single Entity that was generated by this Activity.
PUT /activity/{id} Update an Activity Access Control: You must be the creator of the Activity to modify it.
DELETE /activity/{id} Delete an Activity Access Control: You must be the creator of the Activity to delete it.
GET /activity/{id}/generated Get the Entities that were generatedBy an Activity. Returns a PaginatedResults of Reference objects. Access Control: This service will return Referenc…

Asynchronous Job Services

This is a generic set of services that provides support for both launching asynchronous jobs and monitoring the progress of jobs.

Web Services
Resource Description
POST /asynchronous/job This method is used to launch new jobs. The type of job that will be launched is determined by the passed AsynchronousJobBody. The following are the c…
GET /asynchronous/job/{jobId} Once a job is launched its progress can be monitored by getting its status with this method.

Authentication Services

Provides REST APIs for managing and obtaining the necessary credentials to access Synapse.

Authentication to Synapse services requires an access token passed in the HTTP Authorization header, as per the HTTP bearer authorization standard. The access token incorporates a set of 'scopes' and the documentation for each service requiring authorization lists the scopes which the access token must include in order to use that service.

Synapse currently supports four modes of obtaining an access token:

  • Present username and password
  • Authentication via a whitelisted OAuth 2.0 provider
  • Authentication via a registered OAuth 2.0 client
  • Exchange an access token for Personal Access Token

The username and password are exchanged for an access token using POST /login2 service. This method should only be used by Synapse itself. No other application should prompt a user for their user name and password.

Synapse allows authentication via a white listed OAuth 2.0 provider. Currently only Google is supported. The final step is POST /oauth2/session2 which returns an access token which is included as a Bearer token in the Authorization header of subsequent requests as described above. Only Synapse itself may use this service, as redirection back from the OAuth2 provider is only allowed to the Synapse web portal.

A registered OAuth 2.0 client can use the OAuth 2.0 services to authenticate, the final step of which is a request to the token endpoint: POST /oauth2/token The returned access token is included as a Bearer token in the Authorization header of subsequent requests as described above.

A user may freely generate up to 100 Personal access tokens (PATs) with scoped access using POST /personalAccessToken. Unlike OAuth access tokens,

  • PATs can be freely generated by a user alone and are not linked to any third party OAuth client and
  • While ATs have a strict 24 hour lifetime, PATs are long lived, and will only expire if unused for 180 consecutive days
For these reasons, it is critical to treat PATs as sensitive credentials, like passwords. If a user creates more than 100 tokens, then the least-recently used token(s) will be deleted until the user has no more than 100 tokens.

The returned personal access token is included as a Bearer token in the Authorization header of subsequent requests as described above.

Web Services
Resource Description
POST /login2 Retrieve an access token that will be usable for 24 hours. The user must accept the terms of use before the access token can be used.
GET /authenticatedOn Retrieve the date/time the requesting user was last authenticated, either by presenting their password or by logging in with a recognized identity pro…
POST /user/password/reset Sends an email for resetting a user's password.
POST /user/changePassword Change the current user's password. This will invalidate existing session tokens.
POST /termsOfUse2 Identifies a user by an access token and signs that user's terms of use
GET /secretKey Retrieves the API key associated with the current authenticated user.
DELETE /secretKey Invalidates the API key associated with the current authenticated user. It is not recommended to use this service unless your key has been compromised…
POST /oauth2/authurl The first step in OAuth authentication involves sending the user to authenticate on an OAuthProvider's web page. Use this method to get a properly for…
POST /oauth2/session2 After a user has been authenticated at an OAuthProvider's web page, the provider will redirect the browser to the provided redirectUrl. The provider w…
POST /oauth2/alias After a user has been authenticated at an OAuth provider's web page, the provider will redirect the browser to the provided redirectUrl. The provider …
POST /oauth2/account2 After a user has been authenticated at an OAuthProvider's web page, the provider will redirect the browser to the provided redirectUrl. The provider w…
DELETE /oauth2/alias Remove an alias associated with an account via the OAuth mechanism.
POST /personalAccessToken Issues a personal access token to authorize scoped access to Synapse resources. Note: The scope of the personal access token is the intersection of th…
GET /personalAccessToken Retrieve metadata for all personal access tokens issued for the requesting user. Metadata for active and expired tokens will be returned in reverse-ch…
GET /personalAccessToken/{id} Retrieve metadata for a particular personal access token. Metadata for revoked tokens cannot be retrieved.
DELETE /personalAccessToken/{id} Revoke a personal access token. The token cannot be re-enabled after being revoked.

Authentication Services (2FA)

APIs to manage two factor authentication (2FA) in Synapse.

Synapse currently supports using authenticator applications that can generate a TOTP that is used as a second factor.

To enable 2FA two requests are involved:

  1. POST /2fa/enroll: Generates a shared secret that is added to the user authenticator application
  2. POST /2fa: Enables a specific secret generated by 1. to be used as second factor

In order to login through 2FA an additional request needs to be performed after the user attempts to authenticate (e.g. through the POST /login2 API). If the user has 2FA enabled, they will receive a 401 and the body of the response will contain a twoFaToken that can be used in the POST /2fa/token API to obtain an access token.

The user can additionally generate a set of recovery codes using the POST /2fa/recoveryCodes API. The codes are one time use and can be used in place of a TOTP code when performing 2FA authentication. The body of the POST /2fa/token request should specify as otpType RECOVERY_CODE and the value of the otpCode should match one of the generated codes.

Web Services
Resource Description
POST /2fa/enroll Initiates the enrollment into two factor authentication. Generates a shared secret that can be used by an authenticator application to generate TOTPs.…
POST /2fa Finalize 2FA enrollment, activating the secret associated with the id in the request. This endpoint can be use to replace an existing 2FA secret previ…
GET /2fa Fetch the current 2FA status for the user.
DELETE /2fa Disable 2FA for the user.
POST /2fa/token Performs authentication using 2FA, the body of the request needs to include the twoFaToken received as part of the error when authenticating and the t…
POST /2fa/recoveryCodes Generates a new set of single use recovery codes that are associated with the two factor authentication of the user. The recovery codes are single use…

Certified User Services

To become a Synapse Certified User you must pass a test. The Synapse APIs include a service to provide the test and a service to submit a test result. There are also administrative services to retrieve the history of test submissions.

Web Services
Resource Description
GET /certifiedUserTest Get the test to become a Certified User.
POST /certifiedUserTestResponse Submit a response to the Certified User test.
GET /admin/certifiedUserTestResponse Get the Certified User test responses in the system, optionally filtered by the one who took the test. Note: This service is available to Synapse admi…
DELETE /admin/certifiedUserTestResponse/{id} Delete a test response. Note: This service is available to Synapse administrators only.
GET /user/{id}/certifiedUserPassingRecord Retrieve the Passing Record on the User Certification test for the given user.
GET /admin/user/{id}/certifiedUserPassingRecords Retrieve all the Passing Record on the User Certification test for the given user. Note: This service is available to Synapse administrators only.
PUT /admin/user/{id}/certificationStatus Set a user's certification status. For Synapse administrators only.

Challenge Services

A Challenge is a special object that supplements a project, providing additional features specific to challenges. This set of services provides "CRUD" for Challenge objects and ChallengeTeam objects, which register a Team for a Challenge. The services also provide a number of queries regarding Challenges, challenge participants and challenge Teams.

Web Services
Resource Description
POST /challenge Create a Challenge object, associated with a Project. A participant Team must be specified. To create a Challenge one must have CREATE permission on t…
GET /challenge/{challengeId} Retrieve a Challenge given its ID. To retrieve a Challenge one must have READ permission on the associated Project.
GET /entity/{id}/challenge Retrieve a Challenge given the ID of its associated Project. To retrieve a Challenge one must have READ permission on the Project.
GET /challenge List the Challenges for which the given participant is registered. To be in the returned list the caller must have READ permission on the project asso…
PUT /challenge/{challengeId} Update a Challenge. The caller must have UPDATE permission on the project associated with the Challenge. It is not permitted to change the project ass…
DELETE /challenge/{challengeId} Delete a Challenge. The caller must have DELETE permission on the project associated with the Challenge.
GET /challenge/{challengeId}/participant List the participants registered for a Challenge. The caller must have READ permission on the project associated with the Challenge.
POST /challenge/{challengeId}/challengeTeam Register a Team with a Challenge. You must be a member of the Challenge's participant Team (i.e. you must be already registered for the Challenge) and…
GET /challenge/{challengeId}/challengeTeam List the Teams registered for a Challenge. You must have READ permission in the associated Project to make this request.
GET /challenge/{challengeId}/registratableTeam List the Teams that caller can register for the Challenge, i.e. Teams on which the caller is an administrator and which are not already registered. Th…
PUT /challenge/{challengeId}/challengeTeam/{challengeTeamId} Update a Challenge Team. You must be a member of the Challenge's participant Team (i.e. you must be already registered for the Challenge) and be an ad…
DELETE /challengeTeam/{challengeTeamId} De-register a Team from a Challenge. You must be a member of the Challenge's participant Team (i.e. you must be already registered for the Challenge) …
GET /challenge/{challengeId}/submissionTeams List the Teams under which the given submitter may submit to the Challenge, i.e. the Teams on which the user is a member and which are registered for …

DOI Services

Provides REST APIs for managing Synapse DOIs.

Web Services
Resource Description
GET /doi Retrieves the DOI for the object and its associated DOI metadata. Note: this call calls an external API, which may impact performance To just retrieve…
GET /doi/association Retrieves the DOI for the object. Note: this call only retrieves the DOI association, if it exists. To retrieve the metadata for the object, see GET /…
POST /doi/async/start Asynchronously creates or updates a DOI in Synapse, with input metadata. Retrieve the results with GET /doi/async/get/{asyncToken}. This call may fail…
GET /doi/async/get/{asyncToken} Get the results of a call to POST /doi/async/start
GET /doi/locate Retrieves the Synapse web portal URL to the object entered. Note: This call does not check to see if the object exists in Synapse.

Data Access Services

Some data in Synapse are governed by an ACTAccessRequirement. To gain access to these data, a user must meet all requirements specified in the ACTAccessRequirement.


These services provide the APIs for users to create request to gain access to controlled data, and APIs for the ACT to review and grant access to users.

Web Services
Resource Description
POST /researchProject Create a new ResearchProject or update an existing ResearchProject.
GET /accessRequirement/{requirementId}/researchProjectForUpdate Retrieve an existing ResearchProject that the user owns. If none exists, a ResearchProject with some re-filled information is returned to the user. On…
POST /dataAccessRequest Create a new Request or update an existing Request.
GET /accessRequirement/{requirementId}/dataAccessRequestForUpdate Retrieve the Request for update. If one does not exist, an Request with some re-filled information is returned. If a submission associated with the re…
POST /dataAccessRequest/{requestId}/submission Submit a Submission using information from a Request.
PUT /dataAccessSubmission/{submissionId}/cancellation Cancel a submission. Only the user who created this submission can cancel it.
PUT /dataAccessSubmission/{submissionId} Request to update a submission' state. Only ACT member can perform this action.
POST /accessRequirement/{requirementId}/submissions Retrieve a list of submissions for a given access requirement ID. Allows to optionally filter by submission state and/or id of an accessor setting the…
DELETE /dataAccessSubmission/{submissionId} Delete a submission. Only an ACT member can perform this action.
POST /accessRequirement/{requirementId}/approvedSubmissionInfo Return the research project info for approved data access submissions, ordered by submission modified-on date, descending. Note that accessor changes …
GET /accessRequirement/{requirementId}/status Retrieve an access requirement status for a given access requirement ID.
POST /restrictionInformation Retrieve restriction information on a restrictable object
GET /dataAccessSubmission/openSubmissions Retrieve information about submitted Submissions. Only ACT member can perform this action.
POST /dataAccessSubmission/search Performs a search through access submissions that are reviewable by the user and that match the criteria in the given request. An ACT user can see all…
GET /dataAccessSubmission/{submissionId} Fetch a submission by its id. If the user is a not part of the ACT they must be validated and assigned as reviewers of the AR submissions in order to …

Discussion Services

Discussions in Synapse are captured in the Project's Forum. Each Project has a Forum. Each Forum has a set of Moderators. The Moderators manage the content of the Forum.


A Forum has multiple Threads. A Thread is created by an authorized user. Other authorized users can view and reply to an existing Thread.


These services provide the APIs for Moderators and authorized users to create, edit, and manage the conversations that happen in Synapse.


Web Services
Resource Description
GET /project/{projectId}/forum This API is used to get the Forum's metadata for a given project ID. Target users: anyone who has READ permission to the project.
GET /forum/{forumId} This API is used to get the Forum's metadata for a given its ID. Target users: anyone who has READ permission to the project.
GET /forum/{forumId}/threads This API is used to get N number of threads for a given forum ID. Target users: anyone who has READ permission to the project.
POST /thread This API is used to create a new thread in a forum. Target users: anyone who has READ permission to the project.
GET /thread/{threadId} This API is used to get a thread and its statistic given its ID. Target users: anyone who has READ permission to the project.
PUT /thread/{threadId}/title This API is used to update the title of a thread. Target users: only the author of the thread can update its title.
PUT /thread/{threadId}/message This API is used to update the message of a thread. Target users: only the author of the thread can update its message.
DELETE /thread/{threadId} This API is used to mark a thread as deleted. Target users: only forum's moderator can mark a thread as deleted.
PUT /thread/{threadId}/restore This API is used to restore a deleted thread. Target users: only forum's moderator can restore a deleted thread.
PUT /thread/{threadId}/pin This API is used to mark a thread as pinned. Target users: only forum's moderator can mark a thread as pinned.
PUT /thread/{threadId}/unpin This API is used to unpin a thread. Target users: only forum's moderator can unpin a thread.
GET /thread/messageUrl This API is used to get the message URL of a thread. The message URL is the URL to download the file which contains the thread message. Target users: …
POST /reply This API is used to create a new reply to a thread. Target users: anyone who has READ permission to the project.
GET /reply/{replyId} This API is used to get a reply and its statistic given its ID. Target users: anyone who has READ permission to the project.
PUT /reply/{replyId}/message This API is used to update the message of a reply. Target users: only the author of the reply can update its message.
DELETE /reply/{replyId} This API is used to mark a reply as deleted. Target users: only forum's moderator can mark a reply as deleted.
GET /thread/{threadId}/replies This API is used to get N number of replies for a given thread ID. Target users: anyone who has READ permission to the project.
GET /reply/messageUrl This API is used to get the message URL of a reply. The message URL is the URL to download the file which contains the reply message. Target users: an…
GET /forum/{forumId}/threadcount This API is used to get the total number of threads for a given forum ID. Target users: anyone who has READ permission to the project.
GET /thread/{threadId}/replycount This API is used to get the total number of replies for a given thread ID. Target users: anyone who has READ permission to the project.
GET /entity/{id}/threads This API is used to get N number of threads that belongs to projects user can view and references the given entity. Target users: anyone who has READ …
POST /entity/threadcounts This API is used to get list of entity and count pairs, with count is the number of threads that belong to projects user can view and references the g…
GET /forum/{forumId}/moderators Returns a page of moderators for a given forum ID. Target users: anyone who has READ permission to the project.
POST /forum/{forumId}/search Performs a full text search in the forum defined by the given id. Target users: anyone who has READ permission on the project of the forum.

Docker Authorization Services

These services allow Synapse to act as an authorization service for a Docker Registry. For more details see: https://github.com/docker/distribution/blob/master/docs/spec/auth/token.md Authorization is either:

  • User name and password, included in the request as a Basic Authorization header
  • An oauth access token, passed as a Bearer Authorization header. To execute 'docker pull' the access token must include 'download' scope; to execute 'docker push' the access token must include 'modify' scope and should include 'download' scope.

Web Services
Resource Description
GET /bearerToken Authorize Docker operation. This service is called by the Docker client only and is not for general use.

Docker Commit Services

These services relate to the 'commits' to Docker repositories. Note that create, update and delete of the Docker repositories themselves are done using the Entity Services, for external/unmanaged repositories, or by direct integration with the Docker registry, for managed Docker repositories. Tagged commits for both managed and external/unmanaged repositories may be retrieved using the 'listDockerTags' API included in this service.

Web Services
Resource Description
POST /entity/{id}/dockerCommit Add a commit (tag and digest) for an external/unmanaged Docker repository. (Commits for managed repositories are added via direct integration with the…
GET /entity/{id}/dockerTag List the tagged commits (tag/digest pairs) for the given Docker repository. Only the most recent digest for each tag is returned since, following Dock…

Docker Registry Event Services

These services process events from the Docker Registry. They are separated from other Docker Controllers because the authorization is different, i.e. basic authorization using a key/value pair. These services are not intended to be used by Synapse clients, only by the Docker registry.

Web Services
Resource Description
POST /events Post a list of Docker registry events (pushes and pulls). Synapse will process accordingly. The main purpose is to create managed Docker repositories …

Download List Services

Services for managing a user's download list.

Files can be added to the user's download list using POST /download/list/add. Files can be removed from the user's download by calling either POST /download/list/remove, or the entire list can be cleared with: DELETE /download/list.

In order to query the files on a user's download list, first start an asynchronous job using POST /download/list/query/async/start to get an asynchToken. The job results can be monitored using GET /download/list/query/async/get/{asyncToken}. While the job is still processing the GET call will return a status code of 202 (ACCEPTED). Once the job is complete the GET call will return a status code of 200 with the response body.

Download List Service Limits
resource limit notes
Maximum number of files on a user's download list 100,000 files
Maximum batch size for adding/removing files 1000 files

Web Services
Resource Description
POST /download/list/add A request to add a batch of files to the user’s download list. Authentication is required. A user can only access their own download list.
POST /download/list/remove A request to remove a batch of files from the user's download list. Authentication is required. A user can only access their own download list.
DELETE /download/list Clear all files from the user's download list. Authentication is required. A user can only access their own download list.
POST /download/list/query/async/start Start an asynchronous job to query the user's download list. This call will return an asyncToken that can be used to monitor the job by calling GET /d…
GET /download/list/query/async/get/{asyncToken} Get the results of an asynchronous job to query the user's download list. Started with POST /download/list/query/async/start. While the job is still p…
POST /download/list/add/async/start Start an asynchronous job to add files to a user's download list from either a view query or a folder. Use GET /download/list/add/async/get/{asyncToke…
GET /download/list/add/async/get/{asyncToken} Get the results of an asynchronous job to add files to a user's download list started with: POST /download/list/add/async/start Note: When the result …
POST /download/list/package/async/start Start an asynchronous job to create a zip package of files from a user's download list. After files are added to the a zip package they will be remove…
GET /download/list/package/async/get/{asyncToken} Get the results of an asynchronous job to package files from a user's download list started with: POST /download/list/package/async/start. The respons…
POST /download/list/manifest/async/start Start an asynchronous job to generate a metadata manifest CSV of the available files on the use’s download list. Use GET /download/list/manifest/async…
GET /download/list/manifest/async/get/{asyncToken} Get the results of an asynchronous job to generate a metadata manifest CSV of the available files from the user's download list download list started …

Drs Services

The Data Repository Service API provides access to data objects in single, standard way regardless of where they are stored and how they are managed. The data objects for which information can be fetched are FileEntity and Dataset.The data object that is downloaded is a file.

The supported end points for DRS are:

Use the GET /service-info API to get information about GA4GH-compliant web services, including DRS services, to be aggregated into registries and made available via a standard API.

Use the GET /objects/{object_id} API to get information about individual DRS objects.

Web Services
Resource Description
GET /service-info The service information API will provide information regarding supported GA4GH services. Checkout the drs specification for GA4GH Service Registry
GET /objects/{object_id} The DRSObject API will provide information about a DrsObject, which can be a FileEntity or Dataset. The DrsObject is fetched by its drsId i.e., its Sy…
GET /objects/{object_id}/access/{access_id} This API will provide the url from which a FileEntity may be downloaded. If the file is stored in AWS S3 or a GCP bucket then the result is a time lim…

Entity Bundle Services V2

The Entity Bundle Services provide bundled access to Entities and their related data components. An EntityBundle can be used to create, fetch, or update an Entity and associated objects with a single web service request.

Web Services
Resource Description
POST /entity/{id}/bundle2 Get an entity and related data with a single POST.
POST /entity/{id}/version/{versionNumber}/bundle2 Get an entity at a specific version and its related data with a single POST.
POST /entity/bundle2/create Create an entity and associated components with a single POST. Specifically, this operation supports creation of an Entity, its Annotations, and its A…
PUT /entity/{id}/bundle2 Update an entity and associated components with a single PUT. Specifically, this operation supports update of an Entity, its Annotations, and its ACL.…

Entity Services

All data in Synapse is organize into Projects. These Projects can be further organized into hierarchical Folders. Finally, the data is then represented by FileEntities that reside within Folders or directly within Projects. All these objects (Projects, Folders, FileEntities) are derived from a common object called Entity. The Entity Services provide the means to create, read, update, and delete Synapse Entities. There are also services for navigating the Entity hierarchies , setting Authorization rules, and Annotating Entities.

In addition to the basic entity types (Project, Folder, & FileEntity), Synapse also supports the following Entity types:

The following methods provide the basic Create, Read, Update, Delete (CRUD) for Entities:

Annotations

An Entity can be annotated using the PUT /entity/{id}/annotations2 method. Each annotation is a key-value pair. The GET /entity/{id}/annotations2 method can be used to get the current annotations of an entity.

Authorization

An Entity's authorization is controlled by the Entity's Access Control List (ACL). When a new Project is created a new ACL is automatically created for the Project. New Folders and FileEnties start off inheriting the ACL of their containing Project. This means they do not have their own ACL and all authorization is controlled by their Project's ACL. The term 'benefactor' is used to indicate which Entity an Entity inherits its ACL from. For example, a newly created Project will be its own benefactor, while a new FileEntity's benefactor will start off as its containing Project. The current benefactor of any Entity can be determined using the GET /entity/{id}/benefactor method.

For the case where a Folder or FileEntity needs its own ACL (as opposed to inheriting it from its containing Project) a new ACL can be created for the Entity using the POST /entity/{id}/acl method. When a new ACL is created for an Entity it will no longer inherit its permission from its containing Project and it will become its own benefactor.

While creating or updating an ACL, only Certified Users can add DOWNLOAD permission for Authenticated Users group.

For the case where a Folder or FileEntity no longer needs its own ACL, the ACL can deleted using the DELETE /entity/{id}/acl method. When the ACL of an File or Folder is deleted, it will automatically be assigned the same benefactor as its parent Entity. Deleting the ACL of a Project is not allowed.

The GET /entity/{id}/acl can be used to get an Entity's ACL.

To determine what permissions a User has on an Entity, the GET /entity/{id}/permissions method should be used.

In addition to authorization via ACLs, entities may be restricted via AccessRequirements (ARs). For more information, see Access Requirement Services and Access Approval Services

Versions

Currently, FileEntities are "versionable" meaning it is possible for it to have multiple versions of the file. Whenever, a FileEntity is updated with a new FileHandle whose MD5 differs from the MD5 of the current file hanlde a new version of the FileEntity is automatically created. The history of a FileEntity can be retrieved using GET /entity/{id}/version method. A specific version of a FileEntity can be retrieved using GET /entity/{id}/version/{versionNumber} method. The Annotations of a specific version of an FileEntity can be retrieved using the GET /entity/{id}/version/{versionNumber}/annotations method.

Despite being versionable, Tables, Views and Materialized Views are versioned using snapshots: see POST /entity/{id}/table/snapshot and POST /entity/{id}/table/transaction/async/start.

Note: Only the File and Annotations of an Entity are included in the version. All other components of an Entity such as description, name, parent, ACL, and WikiPage are not not part of the version, and will not vary from version to version.

JSON Schemas

Each Entity type and Model object in Synapse is defined by a JSON schema. The GET /REST/resources method will list the full name of all Resources used by Synapse. The schema for each Resource is accessible via GET /REST/resources/schema. Note: Many of these resources are composition objects and one must navigate various interfaces of an object to fully digest it. Therefore, a flattened (or effective) schema for each resource is available from the GET /REST/resources/effectiveSchema

Entity Service Limits
resource limit
Maximum size of an Entity.name 256 characters
Maximum size of an Entity.desciption 1000 characters
Maximum number of versions for a single Entity 15,000
Maximum number of keys in Annotations 100
Maximum number of values associated with a single key in Annotations 100
Maximum total character count for all values associated with a single key in Annotations when the AnnotationValueType is STRING 500
Maximum hierarchical depth of an Entity 50

Web Services
Resource Description
POST /entity Create a new Entity. This method is used to create Projects, Folders, File Entities, etc. The passed request body should contain the following fields:…
GET /entity/{id} Get an Entity using its ID. Note: To get an Entity the caller must be granted the ACCESS_TYPE.READ on the Entity.
PUT /entity/{id} Update an entity. If the Entity is a FileEntity and the dataFileHandleId fields is set to a new value, then a new version will automatically be create…
PUT /entity/{id}/version/{versionNumber}/filehandle Updates the FileHandle associated with the FileEntity with the provided entity id and version.
DELETE /entity/{id} Moves an entity in the trash can, if the skipTrashCan is set to true will flag the entity for purge and it will be deleted as soon as possible. Note: …
GET /entity/{id}/annotations2 Get the annotations for an entity. Note: The caller must be granted the ACCESS_TYPE.READ on the Entity, to get its annotations.
GET /entity/{id}/version/{versionNumber}/annotations2 Get an Entity's annotations for a specific version of a FileEntity.
PUT /entity/{id}/annotations2 Update an Entity's annotations. Note: The caller must be granted the ACCESS_TYPE.UPDATE on the Entity, to update its annotations.
DELETE /entity/{id}/version/{versionNumber} Delete a specific version of a FileEntity.
GET /entity/{id}/version/{versionNumber} Get a specific version of an Entity. Note: Only the current version of the Entity can be used for an Entity update. Therefore, only the current versio…
GET /entity/{id}/type Get the EntityHeader of an Entity given its ID. The EntityHeader is a light weight object with basic information about an Entity includes its type.
GET /entity/type Get a batch of EntityHeader given multile Entity IDs. The EntityHeader is a light weight object with basic information about an Entity includes its ty…
POST /entity/header Get the EntityHeader for a list of references with a POST. If any item in the batch fails (e.g., with a 404) it will be EXCLUDED in the result set.
GET /entity/{id}/permissions Get the list of permission that the caller has on a given Entity. A User's permission on an Entity is a calculation based several factors including th…
GET /entity/{id}/access Determine if the caller have a given permission on a given Entity. A User's permission on an Entity is a calculation based several factors including t…
GET /entity/{id}/actions/download Returns the list of actions required by the user to gain access to the given entity for download.
GET /entity/{id}/path Get the full path of an Entity as a List of EntityHeaders. The first EntityHeader will be the Root Entity, and the last EntityHeader will be the reque…
POST /entity/{id}/acl Create a new Access Control List (ACL), overriding inheritance. By default, Entities such as FileEntity and Folder inherit their permission from their…
GET /entity/{id}/acl Get the Access Control List (ACL) for a given entity. Note: If this method is called on an Entity that is inheriting its permission from another Entit…
PUT /entity/{id}/acl Update an Entity's ACL. Note: The caller must be granted ACCESS_TYPE.CHANGE_PERMISSIONS on the Entity to call this method.
DELETE /entity/{id}/acl Delete the Access Control List (ACL) for a given Entity. By default, Entities such as FileEntity and Folder inherit their permission from their contai…
GET /entity/{id}/benefactor Get an Entity's benefactor. The term 'benefactor' is used indicate which Entity an Entity inherits is ACL from. For example, a newly created Project w…
GET /entity/{id}/version Get all versions of an Entity one page at a time.
GET /REST/resources Get the list of Resource names for all Resources of Synapse. This includes The full names of each Entity type and Model object of the API. The resulti…
GET /REST/resources/effectiveSchema Get the effective schema of a resource using its name. Many of the Synapse resource are composition objects and one must navigate various interfaces o…
GET /REST/resources/schema Get the full schema of a REST resource. Many of the Synapse resource are composition objects and the various interfaces must be navigated to fully dig…
GET /entity/{id}/generatedBy Get an existing activity for the current version of an Entity.
GET /entity/{id}/version/{versionNumber}/generatedBy Get an existing activity for a specific version of an Entity.
PUT /entity/{id}/generatedBy Sets the generatedBy relationship for the current version of an Entity.
DELETE /entity/{id}/generatedBy Deletes the generatedBy relationship for the current version of an Entity.
GET /entity/{id}/filepreview Get the URL of the preview file associated with the current version of a FileEntity. Note: This call will result in a HTTP temporary redirect (307), t…
GET /entity/{id}/version/{versionNumber}/filepreview Get the URL of the preview file associated with a specific version of a FileEntity. Note: This call will result in a HTTP temporary redirect (307), to…
GET /entity/{id}/filehandles Get the FileHandles of the file currently associated with the current version of the Entity If a preview exists for the file then the handle of the pr…
GET /entity/{id}/version/{versionNumber}/filehandles Get the FileHandles of the file associated with a specific version of a FileEntity. If a preview exists for the file then the handle of the preview an…
GET /entity/md5/{md5} Gets at most 200 FileEntities matching the given MD5 string which the user has read access to. NOTE: Another option is to create a file view that incl…
GET /entity/alias/{alias} Lookup an Entity ID using an alias.
GET /entity/dockerRepo/id For managed docker repositories find the entity id matching the given repository name
POST /entity/children Get a page of children for a given parent ID. This service can also be used to list projects by setting the parentId to NULL in EntityChildrenRequest.…
POST /entity/child Retrieve an entityId for a given parent ID and entity name. This service can also be used to lookup projectId by setting the parentId to NULL in Entit…
PUT /entity/{id}/datatype Change the DataType of the given entity. The entity's DataType controls how the entity can be accessed. For example, an entity's DataType must be set …
GET /entity/{id}/sts Gets the temporary S3 credentials from STS for the given entity. These credentials are only good for the bucket and base key specified by the returned…
PUT /entity/{id}/schema/binding Bind a JSON schema to an Entity. The bound schema will be used to validate the Entity's metadata (annotations). Any child Entity that does not have a …
GET /entity/{id}/schema/binding Get information about a JSON schema bound to an Entity. Note: Any child Entity that does not have a bound schema will inherit the first bound schema f…
DELETE /entity/{id}/schema/binding Clear the bound JSON schema from this Entity. The schema will no longer be used to validate this Entity or its children. Note: The caller must be gran…
GET /entity/{id}/json Get the raw JSON for the given entity. The resulting JSON can be used for the validation of a entity against a JsonSchema. Note: The caller must be gr…
GET /entity/{id}/version/{versionNumber}/json Get the raw JSON for the given entity and version. The resulting JSON can be used for the validation of an entity against a JsonSchema. Note: The call…
PUT /entity/{id}/json Update the annotations of an entity using the raw JSON of the entity. See: GET entity/{id}/json to get the JSON of an entity. Note: The caller must be…
GET /entity/{id}/schema/validation Get the validation results of an Entity against its bound JSON schema. The validation of an Entity against its bound schema is automatic and eventuall…
GET /entity/{id}/schema/validation/statistics Get the The summary statistics of the JSON schema validation results for a single container Entity such as a Project or Folder. Only direct children o…
POST /entity/{id}/schema/validation/invalid Get a single page of invalid JSON schema validation results for a container Entity (Project or Folder). The validation of an Entity against its bound …
GET /entity/{id}/derivedKeys If the given Entity has derived annotations, then this will return the distinct annotation keys of those annotations. If they entity does not have der…

Evaluation Services

The Evaluation API is designed to support open-access data analysis and modeling challenges in Synapse. This framework provides tools for administrators to collect and analyze data models from Synapse users created for a specific goal or purpose.

The data model of the Evaluation API is built around around two primary objects:

  • Evaluation: The primary object representing a Synapse Evaluation. Access to Evaluations is governed by an Access Control List (ACL).
  • Submission: A user in a Synapse Evaluation can submit a Synapse Entity as Submission to that Evaluation. Submission data is owned by the parent Evaluation, and is immutable.

The data model includes additional objects to support scoring of Submissions and convenient data access:

  • SubmissionStatus: An object used to track scoring information for a single Submission. This object is intended to be modified by the users (or test harnesses) managing the Evaluation.
  • SubmissionBundle: A convenience object to transport a Submission and its accompanying SubmissionStatus in a single web service call.
  • SubmissionView: A submission view can be created using the Entity Services providing as scope a list of evaluation ids, in order to query the set of submissions through the Table Query Services. Annotations set in the submissionAnnotations property of a SubmissionStatus can be exposed in the view.

The Evaluation API supports data access mechanisms to monitor Evaluation activity for on-demand scoring and leaderboarding.

Web Services
Resource Description
POST /evaluation Creates a new Evaluation. The passed request body should contain the following fields: name - Give your new Evaluation a name. contentSource - The ID …
GET /evaluation/{evalId} Gets an Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ on the specified Evaluation.
GET /entity/{id}/evaluation Gets Evaluations tied to a project. Note: The response will contain only those Evaluations on which the caller is granted the ACCESS_TYPE.READ permiss…
GET /evaluation Gets a collection of Evaluations, within a given range. Note: The response will contain only those Evaluations on which the caller is granted the ACCE…
GET /evaluation/available Gets a collection of Evaluations in which the user has SUBMIT permission, within a given range. Note: The response will contain only those Evaluations…
GET /evaluation/name/{name} Finds an Evaluation by name. Note: The caller must be granted the ACCESS_TYPE.READ on the specified Evaluation.
PUT /evaluation/{evalId} Updates an Evaluation. Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Each time an Evaluation is updated…
DELETE /evaluation/{evalId} Deletes an Evaluation. Note: The caller must be granted the ACCESS_TYPE.DELETE on the specified Evaluation.
GET /evaluation/{evalId}/team/{id}/submissionEligibility Find out whether a Team and its members are eligible to submit to a given Evaluation queue (at the current time). The request must include an Evaluati…
POST /evaluation/submission Creates a Submission and sends a submission notification email to the submitter's team members. The passed request body should contain the following f…
POST /admin/evaluation/submission/{subId}/contributor Add a contributor to an existing Submission. This service is available to administrators only.
GET /evaluation/submission/{subId} Gets a Submission. Note: The caller must be granted the ACCESS_TYPE.READ_PRIVATE_SUBMISSION on the specified Evaluation.
GET /evaluation/submission/{subId}/status Gets the SubmissionStatus object associated with a specified Submission. Note: The caller must be granted the ACCESS_TYPE.READ on the specified Evalua…
PUT /evaluation/submission/{subId}/status Updates a SubmissionStatus object. Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Each time an Submissio…
PUT /evaluation/{evalId}/statusBatch Update multiple SubmissionStatuses. The maximum batch size is 500. To allow upload of more than this maximum, the system supports uploading of a serie…
DELETE /evaluation/submission/{subId} Deletes a Submission and its accompanying SubmissionStatus. Note: The caller must be granted the ACCESS_TYPE.DELETE_SUBMISSION on the specified Evalua…
GET /evaluation/{evalId}/submission/all Gets a collection of Submissions to a specified Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ_PRIVATE_SUBMISSION on the specified …
GET /evaluation/{evalId}/submission/status/all Gets a collection of SubmissionStatuses to a specified Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ on the specified Evaluation. …
GET /evaluation/{evalId}/submission/bundle/all Gets a collection of bundled Submissions and SubmissionStatuses to a given Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ_PRIVATE_S…
GET /evaluation/{evalId}/submission Gets the requesting user's Submissions to a specified Evaluation.
GET /evaluation/{evalId}/submission/bundle Gets the requesting user's bundled Submissions and SubmissionStatuses to a specified Evaluation.
GET /evaluation/submission/{subId}/file/{fileHandleId} Gets a pre-signed URL to access a requested File contained within a specified Submission. Note: The caller must be granted the ACCESS_TYPE.READ_PRIVAT…
GET /evaluation/{evalId}/submission/count Gets the number of Submissions to a specified Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ_PRIVATE_SUBMISSION on the specified Ev…
GET /evaluation/{evalId}/access Determines whether a specified Synapse user has a certain ACCESS_TYPE on the specified Evaluation.
PUT /evaluation/acl Updates the supplied access control list (ACL) for an evaluation. The ACL to be updated should have the ID of the evaluation. The user should have the…
GET /evaluation/{evalId}/acl Gets the access control list (ACL) governing the given evaluation. The user should have the proper permissions to read the ACL.
GET /evaluation/{evalId}/permissions Gets the user permissions for the specified evaluation.
PUT /evaluation/submission/{subId}/cancellation User requests to cancel their submission. Only the user who submitted a submission can make this request.
POST /evaluation/{evalId}/round Creates a new EvaluationRound to associate with a Evaluation. You must have UPDATE permissions for the associated Evaluation in order to create an Eva…
GET /evaluation/{evalId}/round/{roundId} Retrieve an existing EvaluationRound associated with a Evaluation. You must have READ permissions for the associated Evaluation in order to retrieve a…
POST /evaluation/{evalId}/round/list Retrieve all EvaluationRounds associated with a Evaluation. You must have READ permissions for the associated Evaluation in order to retrieve all Eval…
PUT /evaluation/{evalId}/round/{roundId} Update an existing EvaluationRound to associate with a Evaluation. You must have UPDATE permissions for the associated Evaluation in order to update a…
DELETE /evaluation/{evalId}/round/{roundId} Delete an existing EvaluationRound to associate with a Evaluation. You must have UPDATE permissions for the associated Evaluation in order to delete a…
POST /evaluation/{evalId}/migratequota Migrates the DEPRECATED SubmissionQuota in the "quota" field of an Evaluation into one or many EvaluationRound (depending on the "numberOfRounds" defi…

File Services

A FileHandle is an abstraction for a reference to a file in Synapse. For details on the various types see: FileHandle.

Multi-part File Upload API

In order to ensure file upload is robust, all files must be uploaded to Synapse in 'parts'. This means clients are expected to divide each file into 'parts' and upload each part separately. Since Synapse tracks the state of all multi-part uploads, upload failure can be recovered simply by uploading all parts that Synapse reports as missing.

Note: For multi-part upload 1 MB is defined as 1024*1024 bytes

The first task in multi-part upload is choosing a part size. The minimum part size is 5 MB (1024*1024*5) and the maximum part size is 5 GB (1024*1024*1024*5). Therefore, any file with a size less than or equal to 5 MB will have a single part and a partSize=5242880. The maximum number of parts for a single file 10,000 parts. The following should be used to choose a part size:

partSize = max(5242880, (fileSize/10000))

Once a partSize is chosen, a multi-part upload can be started using the following: POST /file/multipart which will return an MultipartUploadStatus. The client is expected to use MultipartUploadStatus to drive the upload. The client will need to upload each missing part (parts with '0' in the partsState) as follows:

  1. Get a pre-signed URL to upload the part to using: POST /file/multipart/{uploadId}/presigned/url/batch
  2. Upload the part to the pre-signed URL using HTTPs PUT
  3. Add the part to the multi-part upload using: PUT /file/multipart/{uploadId}/add/{partNumber}

Once all parts have been successfully added to the multi-part upload, the upload can be completed using: PUT /file/multipart/{uploadId}/complete to produce a new FileHandle If the upload fails for any reason, the client should start over ( POST /file/multipart) and continue by uploading any parts that are reported as missing.

Multi-part File Copy API

The multipart API supports a robust copy of existing files to other locations (e.g. in case of a data migration) without the need to download and re-upload the file. This is currently supported only from and to S3 storage locations that reside in the same region. In order to initiate a multipart copy, a POST /file/multipart request can be sent using as the body of the request a MultipartUploadCopyRequest.

The part size allows to parallelize the copy in multiple sub-parts, the same limits of the upload applies to the copy (e.g. it is possible to copy a file in a single part up to 5 GB). When initiating a copy we recommend to choose the part size as follows:

partSize = max(104857600, (fileSize/10000))

Once the multipart copy is initiated the process is the same as the multipart upload:

  1. Get the part copy pre-signed URLs using: POST /file/multipart/{uploadId}/presigned/url/batch
  2. For each pre-signed URL perform an HTTP PUT request with no body, the response of the previous endpoint contains a map of headers that are signed with the URL, all of the headers MUST be included in the PUT request.
  3. Once the copy request is performed, add the part to the multi-part copy using: PUT /file/multipart/{uploadId}/add/{partNumber}. The value of the partMD5Hex parameter will be MD5 checksum returned in the response of the request sent to the pre-signed URL.
  4. Once all parts have been successfully added to the multi-part copy, the copy can be completed using: PUT /file/multipart/{uploadId}/complete to produce a new FileHandle

Note about the copy integrity: The resulting file handle will have the same content MD5 of the source file handle, but synapse does not try to re-compute or verify this value. Instead, the integrity check is performed by the cloud provider (currently only S3) during the copy request for the part (the request sent to the pre-signed URL). Each copy pre-signed URL is signed with a special header that makes sure that the source file didn't change during the copy, if this is the case the PUT request to the pre-signed URL will fail and a new copy should be re-started.

Associating FileHandles with Synapse objects

FileHandles can be associated with various type of objects such as a FileEntity and WikiPage. The full list of association types can be found in the FileHandleAssociateType enumeration.

Note that a file handle MUST always be associated with an object, if a file handle is not associated with an objects for more than 30 days Synapse will mark it as UNLINKED and eventually archive or delete it from the system.

For more information see the following:

Service Limits
resource limit notes
Minimum file size 0 bytes
Maximum file size 5 TB (5,497,558,100,000 bytes)
Maximum number of parts 10,000
Minimum file part size 5 MB (5,242,880 bytes) The recommended part size for an upload is max(5242880, (fileSize/10000)). For a copy max(104857600, (fileSize/10000)).
Maximum file part size 5 GB (5,368,709,120 bytes)

Web Services
Resource Description
POST /fileHandle/batch Get a batch of pre-signed URLs and/or FileHandles for the given list of FileHandleAssociations
POST /fileHandle/{handleIdToCopyFrom}/copy Create a copy of an S3FileHandle with a new name and/or content type
GET /fileHandle/{handleId} Get a FileHandle using its ID. Note: Only the user that created the FileHandle can access it directly.
DELETE /fileHandle/{handleId} Delete a FileHandle using its ID. Note: Only the user that created the FileHandle can delete it. Also, a FileHandle cannot be deleted if it is associa…
DELETE /fileHandle/{handleId}/filepreview Delete the preview associated with the given FileHandle. This will cause Synapse to automatically generate a new preview.
POST /externalFileHandle Create an ExternalFileHandle to represent an external URL. Synapse will attempt to generate a preview for any external URL that can be publicly read. …
POST /externalFileHandle/s3 Create an S3FileHandle to represent an S3Object in a user's S3 bucket. In order to use this method an ExternalS3StorageLocationSetting must first be c…
POST /externalFileHandle/googleCloud Create an GoogleCloudFileHandle to represent a Google Cloud Blob in a user's Google Cloud bucket. In order to use this method an ExternalGoogleCloudSt…
GET /entity/{id}/uploadDestinationLocations Get the upload destination locations available for this parent entity. This will return a list of at least one destination location. The first destina…
GET /entity/{id}/uploadDestination/{storageLocationId} Get the upload destination associated with the given storage location id. This will always return an upload destination
GET /entity/{id}/uploadDestination Get the default upload destination for the entity with the given id. The id might refer to the parent container (e.g. a folder or a project) where a f…
GET /fileHandle/{handleId}/url Get a URL that can be used to download a file of a FileHandle. Note: This call will result in a HTTP temporary redirect (307), to the actual file URL …
POST /file/bulk/async/start Start an asynchronous job to download multiple files in bulk. This job will generate a zip file that contains each requested file that the caller is a…
GET /file/bulk/async/get/{asyncToken} Get the results of a bulk file download started with POST /file/bulk/async/start Note: When the result is not ready yet, this method will return a sta…
GET /file/{id} Get the actual URL of the file from with an associated object . Note: This call will result in a HTTP temporary redirect (307), to the actual file URL…
POST /file/multipart Start or resume a multi-part upload or copy of a file. By default this method is idempotent, so subsequent calls will simply return the current status…
POST /file/multipart/{uploadId}/presigned/url/batch Get a batch of pre-signed URLS that should be used to upload or copy file parts. Each part will require a unique pre-signed URL. For an upload the cli…
PUT /file/multipart/{uploadId}/add/{partNumber} After the contents of part have been uploaded or copied with the PUT to the part pre-signed URL this service is used to confirm the addition of the pa…
PUT /file/multipart/{uploadId}/complete After all of the parts have been upload and added successfully, this service is called to complete the upload resulting in the creation of a new file …
POST /filehandles/copy Copy a batch of FileHandles. This API will check for DOWNLOAD permission on each FileHandle. If the user has DOWNLOAD permission on a FileHandle, we w…
POST /download/list/add/async/start Start an asynchronous job to add files to a user's download list. Note: There is a limit of 100 files on a user's download list. Use GET /download/lis…
GET /download/list/add/async/get/{asyncToken} Get the results of an asynchronous job to add files to a user's download list started with: POST /download/list/add/async/start Note: When the result …
POST /download/list/add Add the given list of FileHandleAssociations to the caller's download list. Note: There is a limit of 100 files on a user's download list.
POST /download/list/remove Remove the given list of FileHandleAssociations to the caller's download list.
DELETE /download/list Clear the caller's download list.
GET /download/list Get the user's current download list.
POST /download/order Create a download Order from the user's current download list. Only files that the user has permission to download will be added to the download order…
GET /download/order/{orderId} Get a download order given its orderId. Only the user that created the order can get it.
POST /download/order/history Get the caller's download order history in reverse chronological order. This is a paginated call.
POST /fileHandle/restore/async/start Starts an asynchronous job to restore a batch of file handles that were ARCHIVED or UNLINKED. The file handles status will be set as AVAILABLE. Note t…
GET /fileHandle/restore/async/get/{asyncToken} Get the results of an asynchronous job to restore a batch of files handles started with: POST /fileHandle/restore/async/start. The response includes f…

Form Services

Collection of APIs from managing and submitting form data. There are two basic objects:

  • FormData - Represent an end user's data gathered from a form template. All FormData belongs to a single FormGroup.
  • FormGroup - Represents a grouping of FormData with an Access Control List (ACL) for administration. The ACL controls both who can submit data to the group and who has access to the submitted data.

To download the data associated with a FormData object use: POST /fileHandle/batch providing the formData.dataFileHandleId with FileHandleAssociateType.FormData

Web Services
Resource Description
POST /form/group Create a FormGroup with the provided name. This method is idempotent. If a group with the provided name already exists and the caller has ACCESS_TYPE.…
GET /form/group/{id} Get a FormGroup with the provided ID. Note: The caller must have the ACCESS_TYPE.READ permission on the identified group.
GET /form/group/{id}/acl Get the Access Control List (ACL) for a FormGroup. Note: The caller must have the ACCESS_TYPE.READ permission on the identified group.
PUT /form/group/{id}/acl Update the Access Control List (ACL) for a FormGroup. The following define the permissions in this context: READ - Grants read access to the group. RE…
POST /form/data Create a new FormData object. The caller will own the resulting object and will have access to read, update, and delete the FormData object. Note: The…
PUT /form/data/{id} Update an existing FormData object. The caller must be the creator of the FormData object. Once a FormData object has been submitted, it cannot be upd…
DELETE /form/data/{id} Delete an existing FormData object. The caller must be the creator of the FormData object. Note: Cannot delete a FormData object once it has been subm…
POST /form/data/{id}/submit Submit the identified FormData from review. Note: The caller must have the SUBMIT permission on the identified group to update the group's ACL.
POST /form/data/list List FormData objects and their associated status that match the filters of the provided request that are owned by the caller. Note: Only objects owne…
POST /form/data/list/reviewer List FormData objects and their associated status that match the filters of the provided request for the entire group. This is used by service account…
PUT /form/data/{id}/accept Called by the form reviewing service to accept a submitted data. Note: The caller must have the READ_PRIVATE_SUBMISSION permission on the identified g…
PUT /form/data/{id}/reject Called by the form reviewing service to reject a submitted data. Note: The caller must have the READ_PRIVATE_SUBMISSION permission on the identified g…

JSON Schema Services

This set of services provide project designers with tools to define their own schemas to control and validate metadata applied to Projects, Folders, and Files. All schemas are defined using JSON schemas following json-schema.org specification.

To get started, you will need to either create a new Organization or join an existing Organization. Each Organization has an AccessControlList (ACL) that controls which users/teams are authorized to contribute schemas under that Organization's name-space. The Organization's name-space is referenced using the Organization's name, which is also the root of all schema $ids within the Organization.

Web Services
Resource Description
POST /schema/organization Create a new Organization by providing a unique organization name. The new Organization will have an auto-generated AcessControlList (ACL) granting th…
GET /schema/organization Lookup an Organization by name.
POST /schema/organization/list List all organizations. Each call will return a single page of Organizations. Forward the provided nextPageToken to get the next page.
DELETE /schema/organization/{id} Delete the identified Organization. All schemas defined within the Organization's name-space must first be deleted before an Organization can be delet…
GET /schema/organization/{id}/acl Get the AcessControlList (ACL) associated with the identified Organization. Note: The caller must be granted the ACCESS_TYPE.READ permission to get an…
PUT /schema/organization/{id}/acl Update the AccessControlList (ACL) for the identified Organization. Note: The caller must be granted the ACCESS_TYPE.CHANGE_PERMISSIONS permission to …
POST /schema/type/create/async/start Start an asynchronous job to create a new JSON schema. A JSON schema must include an $id that is a relative URL of that schema. The pseudo-BNF syntax …
GET /schema/type/create/async/get/{asyncToken} Get the results of an asynchronous job that was started to create a new JSON schema. * Note: If the job has not completed, this method will return a s…
GET /schema/type/registered/{id} Get a registered JSON schema using its $id.
POST /schema/list List all JSON schemas for an Organization. Each call will return a single page of schemas. Forward the provided nextPageToken to get the next page.
POST /schema/version/list List the version information for each version of a given schema. Each call will return a single page of results. Forward the provide nextPageToken to …
DELETE /schema/type/registered/{id} Delete the given schema using its $id. If the $id excludes a semantic version, all versions of the schema will be deleted. If the $id includes a seman…
POST /schema/type/validation/async/start To use a JSON schema for validation, the JSON schema plus all of its dependency schemas must be provided to a JSON schema validator. The 'validation' …
GET /schema/type/validation/async/get/{asyncToken} Get the results of an asynchronous job that was started to compile a 'validation' schema for a JSON schema. Note: If the job has not completed, this m…

Log Service

https://sagebionetworks.jira.com/wiki/display/PLFM/Repository+Service+API#RepositoryServiceAPI-QueryAPI

Web Services
Resource Description
POST /log Logs the entry in the Synapse service logs. Clients can use this to log errors that the service should know about.

Membership Invitation Services

The Membership Invitation Services create, retrieve and delete membership invitations. A membership invitation is created by a Team administrator to invite a Synapse user to join the Team. Without the invitation it is not possible for an outside user to join. For more on Teams, see Team Services.

Web Services
Resource Description
POST /membershipInvitation Create a membership invitation and send an email notification to the invitee. The team must be specified. Also, either an inviteeId or an inviteeEmail…
GET /user/{id}/openInvitation Retrieve the open invitations to a user, optionally filtering by the Team of origin. An invitation is only open if it has not expired and if the user …
GET /team/{id}/openInvitation Retrieve the open invitations from a Team, optionally filtering by the invitee. An invitation is only open if it has not expired and if the user has n…
GET /membershipInvitation/{id} Retrieve an invitation by ID Note: The client must be an administrator of the Team referenced by the invitation or the invitee to make this request.
POST /membershipInvitation/{id} Retrieve an invitation by ID using a MembershipInvtnSignedToken for authorization
DELETE /membershipInvitation/{id} Delete an invitation Note: The client must be an administrator of the Team referenced by the invitation or the invitee to make this request.
GET /membershipInvitation/openInvitationCount Retrieve the number of pending Membership Invitations
GET /membershipInvitation/{id}/inviteeVerificationSignedToken Verify whether the inviteeEmail of the indicated MembershipInvitation is associated with the authenticated user. If it is, the response body will cont…
PUT /membershipInvitation/{id}/inviteeId Set the inviteeId of a MembershipInvitation. A valid InviteeVerificationSignedToken must have an inviteeId equal to the id of the authenticated user a…

Membership Request Services

The Membership Request Services create, retrieve and delete membership requests. A membership request is created by a Synapse user to request admission to a Team. Without the request it is not possible for a Team to admit the user. For more on Teams, see Team Services.

Web Services
Resource Description
POST /membershipRequest Create a membership request and send an email notification to the administrators of the team. The Team must be specified. Optionally, the creator may …
GET /team/{id}/openRequest Retrieve the open requests submitted to a Team, optionally filtering by the requester. An request is only open if it has not expired and if the reques…
GET /user/{id}/openRequest Retrieve the open requests submitted by a user, optionally filtering by the Team. An request is only open if it has not expired and if the requester h…
GET /membershipRequest/{id} Retrieve an request by ID Note: The client must be the creator of the membership request to make this request.
DELETE /membershipRequest/{id} Delete a request Note: The client must be the creator of the membership request to make this request.
GET /membershipRequest/openRequestCount Retrieve the number of pending Membership Requests for teams that user is admin

Message Services

Provides REST APIs for sending messages to other Synapse users and for commenting on Synapse entities.

Web Services
Resource Description
POST /message Sends a message. The "fileHandleId" field should point to a plain text file containing the body of the message. The file should be uploaded prior to t…
POST /cloudMailInMessage Note: This service is designed to be used by CloudMailIn, not by clients in general. Calling the service requires Basic Authentication credentials own…
POST /cloudMailInAuthorization Note: This service is designed to be used by CloudMailIn, not by clients in general.
GET /message/inbox Retrieves the current authenticated user's inbox. It may take several seconds for a message to appear in the inbox after creation. By default, the mos…
GET /message/outbox Retrieves the current authenticated user's outbox. By default, the most recent messages are returned first. To flip the ordering, set the "descending"…
GET /message/{messageId} Fetches the specified message. The authenticated user must be either the sender or receiver of the message.
POST /message/{messageId}/forward Forwards a message to the specified set of recipients. The authenticated user must be either the sender or receiver of the forwarded message.
GET /message/{messageId}/conversation Retrieves messages belonging to the same thread as the given message. The current authenticated user will be either the sender or receiver of all retu…
PUT /message/status Updates the current status of a message relative to the current authenticated user. Note: the "recipientId" field of the request body will be ignored.…
DELETE /admin/message/{messageId} Deletes a message. Only accessible to administrators.
GET /message/{messageId}/file Get the actual URL of the file associated with the message Note: This call will result in a HTTP temporary redirect (307), to the actual file URL if t…
POST /entity/{id}/message Adds the owner of the given entity as an additional recipient of the message. Afterwards, behavior is identical to POST /message

OpenID Connect Services

The OpenID Connect (OIDC) services implement OAuth 2.0 with the OpenID identity extensions.

Web Services
Resource Description
GET /.well-known/openid-configuration Get the Open ID Configuration ("Discovery Document") for the Synapse OIDC service.
GET /oauth2/jwks Get the JSON Web Key Set for the Synapse OIDC service. This is the set of public keys used to verify signed JSON Web tokens generated by Synapse.
POST /oauth2/client Create an OAuth 2.0 client. Note: The client name must be unique. Note: After creating the client one must also set the client secret and have their c…
POST /oauth2/client/secret/{id} Get a secret credential to use when requesting an access token. See the Open ID Connect specification for client authentication Synapse supports 'clie…
GET /oauth2/client/{id} Get an existing OAuth 2.0 client. When retrieving one's own client, all metadata is returned. It is permissible to retrieve a client anonymously or as…
GET /oauth2/client List the OAuth 2.0 clients created by the current user.
PUT /oauth2/client/{id}/verificationPrecheck Check whether the proposed change to an OAuth Client will cause the client to enter the 'unverified' state. This service also validates the submitted …
PUT /oauth2/client/{id} Update the metadata for an existing OAuth 2.0 client. Note: Only the creator of a client can update it. Note: Changing the redirect URIs and/or the se…
DELETE /oauth2/client/{id} Delete OAuth 2.0 client
POST /oauth2/description Get a user-readable description of the authentication request. This request does not need to be authenticated.
POST /oauth2/consentcheck Check whether user has already granted consent for the given OAuth client, scope, and claims. Consent persists for one year.
POST /oauth2/consent Get authorization code for a given client, scopes, response type(s), and extra claim(s). See: Open ID Connect specification for consent. Open ID Conne…
POST /oauth2/token Get access, refresh and id tokens, as per the Open ID Connect specification for the token request. Request must include client ID and Secret in Basic …
GET /oauth2/userinfo The result is either a JSON Object or a JSON Web Token, depending on whether the client registered a signing algorithm in its userinfo_signed_response…
POST /oauth2/userinfo The result is either a JSON Object or a JSON Web Token, depending on whether the client registered a signing algorithm in its userinfo_signed_response…
GET /oauth2/audit/grantedClients Get a paginated list of the OAuth 2 clients that currently have active refresh tokens that grant access to the user's Synapse identity and/or resource…
GET /oauth2/audit/grantedClients/{clientId}/tokens Get a paginated list of metadata about refresh tokens granted to a particular OAuth 2 client on behalf of the requesting user. The token itself may no…
GET /oauth2/audit/tokens/{tokenId}/metadata Retrieve the metadata for an OAuth 2.0 refresh token as an authenticated Synapse user. Clients that wish to retrieve OAuth 2.0 refresh token metadata …
GET /oauth2/token/{tokenId}/metadata Retrieve the metadata for an OAuth 2.0 refresh token. The request should be made as an OAuth 2.0 client using basic authentication. Users that wish to…
PUT /oauth2/audit/tokens/{tokenId}/metadata Update the metadata for a refresh token. At this time, the only field that a user may set is the 'name' field.
POST /oauth2/audit/grantedClients/{clientId}/revoke Revoke all refresh tokens and their related access tokens associated with a particular client and the requesting user. Note that access tokens that ar…
POST /oauth2/audit/tokens/{tokenId}/revoke Revoke a particular refresh token and all of its related access tokens using its unique ID. The caller must be the the user/resource owner associated …
POST /oauth2/revoke Revoke a particular refresh token using the token itself, or an associated access token. The caller must be the the client associated with the refresh…

Principal Services

A Principal in Synapse can be a User, Group, or a Team. This is a set of services that provides the means to look-up principals by their various attributes and also to test unique names such as USER_NAME, USER_EMAIL, or TEAM_NAME are available for use.

Web Services
Resource Description
POST /principal/available This call is used to determine if an alias is currently available. Authentication is not required for this call. Each value of each AliasType must hav…
POST /account/emailValidation This service starts the process of creating a new account by sending a 'validation email' message to the provided email address. The email contains a …
POST /account2 This service completes the email validation process for setting up a new account. The client must provide the validation token which was sent by email…
POST /account/{id}/emailValidation This service starts the process of adding a new email address to an existing account by sending a 'validation email' message to the provided email add…
POST /email This service completes the email validation process for adding a new email address to an existing account. The client must provide the validation toke…
DELETE /email This service removes an email address from an account. The request is rejected if the email address is not currently owned by the user or if the email…
PUT /notificationEmail This service sets the email used for user notifications, i.e. when a Synapse message is sent and if the user has elected to receive messages by email,…
GET /notificationEmail This service returns the email used for user notifications, i.e. when a Synapse message is sent and if the user has elected to receive messages by ema…
POST /principal/alias Lookup a principal ID using an alias and alias type.

Project Settings Services

The project settings services provide configuration options that can be applied to projects. In particular through the POST /projectSettings and PUT /projectSettings services a user can create or update the setting of a specific type for a project.

Currently supported settings for a project are:

The POST /storageLocation service is provided in order to create StorageLocationSetting. The id of a StorageLocationSetting can then be set in the locations property of the UploadDestinationListSetting.

When uploading a file the id of the default StorageLocationSetting to be used on a folder can be retrieved using the GET /entity/{id}/uploadDestination service using the id of the parent entity (e.g. a folder or a project).

By setting a custom storage location, users can store the data in their own S3 or Google Cloud bucket. Note that when a folder or a project is configured to use a custom storage location, only future uploads through Synapse are affected (e.g. changing the storage location does not automatically change the location of existing files). For a guide on setting a custom storage location, see the Custom Storage Location documentation article.

Web Services
Resource Description
GET /projectSettings/{id} Gets the ProjectSetting with the given id. Note that this is not the id of a project, in order to retrieve the project settings by the project id plea…
GET /projectSettings/{projectId}/type/{type} Gets the ProjectSetting of a particular type for the project with the given id. Currently supported types: upload: Used to retrieve the UploadDestinat…
POST /projectSettings Create a ProjectSetting for a project. The setting may be any of the implementations of ProjectSetting. Only the users with CREATE access to the proje…
PUT /projectSettings Update an existing ProjectSetting. Only the users with UPDATE access to the project can update a project setting. Currently supports: UploadDestinatio…
DELETE /projectSettings/{id} Deletes a ProjectSetting. Only the users with DELETE access to the project can delete a project setting.
POST /storageLocation Creates a StorageLocationSetting, which can be associated with a project for users to upload their data to a user-owned location. The request object s…
GET /storageLocation/{id} Get the StorageLocationSetting with the given id. Only the creator of the StorageLocationSetting can retrieve it by its id.

Recycle Bin Services

The recycle bin (or trash can) is the special folder that holds the deleted entities for users.

Services are provided for users to delete entities into the trash can, to view entities in the trash can, to purge entities from the trash can, and to restore entities out of the trash can.

Web Services
Resource Description
PUT /trashcan/trash/{id} Moves an entity and its descendants to the trash can.
PUT /trashcan/restore/{id} Moves an entity and its descendants out of the trash can back to its original parent. An exception is thrown if the original parent does not exist any…
PUT /trashcan/restore/{id}/{parentId} Moves an entity and its descendants out of the trash can to a new parent. NOTE: This operation cannot be completed if the original parent has been del…
GET /trashcan/view Retrieves the paginated list of trash entities deleted by the current user.
PUT /trashcan/purge/{id} Flags the specified entity for priority purge. The entity will be deleted as soon as possible. Once purging is done, the entity will be permanently de…

Search Services

Search for Entities on Synapse

Web Services
Resource Description
POST /search Searches for Entitys that are accessible by the current user. If not authenticated, only public result will be shown. See SearchFieldName for the list…

Statistics Services

Services that expose statistics computed by the backend.

Web Services
Resource Description
POST /statistics Generic endpoint to retrieve statistics about objects. The user should have READ access on the object referenced by the objectId in the request. Curre…

Storage Report Services

Provides REST APIs for generating Storage Reports. These may only be used by the Synapse Report Team.

Web Services
Resource Description
POST /storageReport/async/start Asynchronously creates a report detailing the usage of Synapse storage with project-level resolution. Retrieve the results with GET /storageReport/asy…
GET /storageReport/async/get/{asyncToken} Get the results of a call to POST /storageReport/async/start

Subscription Services

While working in Synapse, users may want to subscribe to different topics to receive notifications about changes in those topics.


These services provide the APIs for Synapse users to manage their subscriptions.


Web Services
Resource Description
POST /subscription This API is used to subscribe to a topic. Target users: anyone who has READ permission on the object.
POST /subscription/all This API is used to subscribe to all topic of the same SubscriptionObjectType. Only the following SubscriptionObjectType are allowed in this API: DATA…
POST /subscription/list This API is used to retrieve subscriptions one has based on a list of provided topics. These topics must have the same objectType. Target users: all S…
GET /subscription/{id} This API is used to retrieve a subscription given its ID Target users: Synapse user who created this subscription.
GET /subscription/all This API is used to retrieve all subscriptions one has. Target users: all Synapse users.
DELETE /subscription/{id} This API is used to unsubscribe to a topic. Target users: Synapse user who created this subscription.
DELETE /subscription/all This API is used to unsubscribe all topics one followed. Target users: Synapse users
POST /subscription/subscribers Retrieve subscribers for a given topic.
POST /subscription/subscribers/count Retrieve number of subscribers for a given topic.

Table Services

A Synapse TableEntity model object represents the metadata of a table. Each TableEntity is defined by a list of ColumnModel IDs. Use POST /column to create new ColumnModel objects. Each ColumnModel object is immutable, so to change a column of a table a new column must be added and the old column must be removed. TableEntities can be created, updated, read and deleted like any other entity:

All ColumnModel objects are publicly viewable and usable. Since each ColumnModel is immutable it is safe to re-use ColumnModels created by other users. Use the GET /column services to list all of the existing ColumnModels that are currently in use.

Once the columns for a TableEntity have been created and assigned to the TableEntity, rows can be added to the table using POST /entity/{id}/table/transaction/async/start. Each Row appended to the table will automatically be assigned a rowId and a versionNumber and can be found in the resulting RowReferenceSet. To update a row, simply include the row's rowId in the passed RowSet. Any row without a rowId will be treated as a new row. When a row is updated a new versionNumber will automatically be assigned the Row. While previous versions of any row are kept, only the current version of any row will appear in the table index used to support the query service: POST /entity/{id}/table/query/async/start

Use the POST /entity/{id}/table/query/async/start services to query for the current rows of a table. The returned RowSet of the table query can be modified and returned to update the rows of a table using POST /entity/{id}/table/transaction/async/start.

There is also an asynchronous service to upload and download csv files, suitable for large datasets.

Table Service Limits

resource limit notes
Maximum size of column names 256 characters
Maximum number of enumeration values for a single column 100
Maximum number of columns per table/view 152
The maximum possible width of a table/view 64 KB Each ColumnType has a maximum possible size. The total width of a table/view is the sum of the maximum size of each of its columns
The maximum number of LARG_TEXT columns per table/view 30
Maximum table size ~146 GB All row changes applied to a table are automatically batched into changes sets with a maximum size of 5242880 bytes (5 MB). Currently, there is a limit of 30,000 change sets per table. Therefore, the theoretical maximum size of table is 5242880 bytes * 30,000 = ~ 146 GB.
The maximum number of projects/folder per view scope 30 K Recursive sub-folders count towards this limit. For example, if a project contains more than 30 K sub-folders then it cannot be included in a view's scope.
The maximum number of rows per view 200 M A single folder cannot contain more then 10 K files/folders. Since a view's scope is limited to 30 K project/folders, the maximum number of rows per view is 10 K * 30 K = 300 M.
The maximum file size of a CSV that can be appended to a table 1 GB
The maximum size of a single query result 512000 bytes
Entity View only: The maximum total character length for a STRING or STRING_LIST ColumnType 500 characters Entity Views ONLY! This follows limitations placed on Annotations. For the type STRING_LIST, the total character count is the cumulative length of all string contained in the list.
Entity View only: The maximum list length for "_LIST" suffixed ColumnType 100 values Entity Views ONLY! This follows limitations placed on Annotations.

Web Services
Resource Description
POST /column Create a ColumnModel that can be used as a column of a TableEntity. Unlike other objects in Synapse ColumnModels are immutable and reusable and do not…
POST /column/batch Create a batch of ColumnModel that can be used as columns of a TableEntity. Unlike other objects in Synapse ColumnModels are immutable and reusable an…
GET /column/{columnId} Get a ColumnModel using its ID.
GET /entity/{id}/column Given the ID of a TableEntity, get its list of ColumnModels that are currently assigned to the table. Service Limits resource limit The maximum freque…
GET /column List all of the ColumnModels that have been created in Synapse. Since each ColumnModel is immutable it is safe to re-use ColumnModels created by other…
GET /column/tableview/defaults Get the list of default ColumnModels for the given viewEntityType and viewTypeMask.
POST /entity/{id}/table/transaction/async/start Start a table update job that will attempt to make all of the requested changes in a single transaction. All updates will either succeed or fail as a …
GET /entity/{id}/table/transaction/async/get/{asyncToken} Asynchronously get the results of a table update transaction started with POST /entity/{id}/table/transaction/async/start Note: When the result is not…
POST /entity/{id}/table/filehandles This method is used to get file handle information for rows in a TableEntity. The columns in the passed in RowReferenceSet need to be FILEHANDLEID col…
GET /entity/{id}/table/column/{columnId}/row/{rowId}/version/{versionNumber}/file Get the actual URL of the file associated with a specific version of a row and file handle column. Note: This call will result in a HTTP temporary red…
GET /entity/{id}/table/column/{columnId}/row/{rowId}/version/{versionNumber}/filepreview Get the preview URL of the file associated with a specific version of a row and file handle column. Note: This call will result in a HTTP temporary re…
POST /entity/{id}/table/query/async/start Asynchronously start a query. Use the returned job id and GET /entity/{id}/table/query/async/get to get the results of the query Using a 'SQL like' sy…
GET /entity/{id}/table/query/async/get/{asyncToken} Asynchronously get the results of a query started with POST /entity/{id}/table/query/async/start. Note: When the result is not ready yet, this method …
POST /entity/{id}/table/download/csv/async/start Asynchronously start a csv download. Use the returned job id and GET /entity/{id}/table/download/csv/async/get to get the results of the query
GET /entity/{id}/table/download/csv/async/get/{asyncToken} Asynchronously get the results of a csv download started with POST /entity/{id}/table/download/csv/async/start Note: When the result is not ready yet,…
POST /table/upload/csv/preview/async/start The method can be used to test both the parameters for reading an upload CSV file and the required table schema. The caller can then adjust both param…
GET /table/upload/csv/preview/async/get/{asyncToken} Asynchronously get the results of a csv upload preview started with POST /table/upload/csv/async/start Note: When the result is not ready yet, this me…
POST /entity/{id}/table/upload/csv/async/start Asynchronously start a csv upload. Use the returned job id and GET /entity/{id}/table/upload/csv/async/get to get the results of the query Service Lim…
GET /entity/{id}/table/upload/csv/async/get/{asyncToken} Asynchronously get the results of a csv upload started with POST /entity/{id}/table/upload/csv/async/start Note: When the result is not ready yet, thi…
POST /column/view/scope/async/start Starts an asynchronous job to compute a page of the possible ColumnModels based on the annotations within the provided scope. The result of the job ca…
GET /column/view/scope/async/get/{asyncToken} Fetches the result of the POST /column/view/scope/async/start service that'll contain a page of possible ColumnModels within the scope supplied in the…
POST /entity/{id}/table/snapshot Request to create a new snapshot of a table. The provided comment, label, and activity ID will be applied to the current version thereby creating a sn…
POST /validateDefiningSql Validate the potential definingSQL for a view before the creation of the view.

Team Services

Teams are groups of users. Teams can be granted access permissions to projects, folders and files, and share other resources by adding them to Access Control Lists (ACLs). Any authenticated Synapse user may create a Team, for which they become an administrator. Team administrators may:

  • invite other users to join the Team,
  • accept membership requests from users wishing to join the Team,
  • grant or revoke administrative control to Team members,
  • remove a user from the Team.

Other Synapse users may:
  • issue membership requests to a Team,
  • accept Team membership invitations (join the Team),
  • unilaterally choose to leave a Team once added.

Web Services
Resource Description
POST /team Create a new Team. The passed request body may contain the following fields: name - Give your new Team a name. The name must be unique, not used by an…
GET /teams Retrieve a paginated list of Teams matching the supplied name fragment (optional), in alphabetical order by Team name. Note: This service has JSONP su…
GET /user/{id}/team Retrieve a paginated list of Teams to which the given user belongs.
GET /user/{id}/team/id Retrieve a paginated list of IDs of Teams to which the given user belongs. If sorting is desired, both sort and ascending must be specified. If they a…
POST /teamList Retrieve a list of Teams given their IDs. Invalid IDs in the list are ignored: The results list is simply smaller than the list of IDs passed in.
GET /team/{id}/member/{principalId} Service Limits resource limit The maximum frequency this method can be called 1 calls per second
GET /team/{id} Retrieve the metadata for a specified Team. Service Limits resource limit The maximum frequency this method can be called 1 calls per second
GET /team/{id}/icon Retrieve the download URL for the Team icon, or receive a redirect response to said URL.
GET /team/{id}/icon/preview Retrieve the download URL for the Team icon preview, or receive a redirect response to said URL.
PUT /team Update the Team metadata for the specified Team. Note: The client must be a Team administrator to make this request.
DELETE /team/{id} Delete the Team. Note: The client must be a Team administrator to make this request.
PUT /team/{id}/member/{principalId} Add a member to the Team. If the one making the request is the user to be added, then the user must have an open invitation from the Team. If the one …
PUT /teamMember Add a member to the Team. Note: The request is authenticated by a hash message authentication code in the request body, generated by Synapse. The inte…
GET /team/{id}/member/{principalId}/membershipStatus Retrieve the Team Membership Status bundle for a team and user. This says whether a user is a member of a Team, whether there are outstanding membersh…
GET /teamMembers/{id} Retrieve a paginated list of Team members matching the supplied name prefix. If the prefix is omitted then all members are returned. Note: This servic…
GET /teamMembers/count/{id} Retrieve the number of Team members matching the supplied name prefix. If the prefix is omitted then the number of members in the team is returned. No…
POST /team/{id}/memberList Returns the TeamMember info for a team and a given list of members' principal IDs. Invalid IDs in the list are ignored: The results list is simply sma…
POST /user/{id}/memberList Returns the TeamMember info for a user and a given list of Team IDs. Not Found status is returned if the user ID is invalid, any of the Team IDs are i…
DELETE /team/{id}/member/{principalId} Remove the given member from the specified Team. Note: The client must either be a Team administrator or the member being removed.
GET /team/{id}/acl Retrieve the AccessControlList for a specified Team.
PUT /team/acl Update the Access Control List for the specified Team.

User & Group Services

Web Services
Resource Description
GET /userGroup Get the user-groups in the system

User Profile Services

Every Synapse user has an associated UserProfile.

Web Services
Resource Description
GET /userProfile Get the profile of the caller (my profile). Note: Private user profile fields will be returned.
GET /user/bundle Get the user bundle of the caller (my own bundle). Note: Private fields will be returned.
GET /userProfile/{profileId} Get the profile of a specified user. Note: Private fields (e.g. "rStudioUrl") are omitted unless the requester is the profile owner or an administrato…
GET /user/{id}/bundle Get the user bundle of a specified user. Note: Private fields (e.g. "rStudioUrl") are omitted unless the requester is the profile owner or an administ…
GET /user Get all publicly available UserProfile data in the system
PUT /userProfile Update your own profile Note: The user associated with the UserProfile "ownerId" must match the identity of the caller, otherwise an Unauthorized resp…
PUT /notificationSettings Update email notification settings. Note: The request is authenticated by a hash message authentication code, generated by Synapse. The intended use o…
GET /userGroupHeaders/batch Batch get UserGroupHeaders. This fetches information about a collection of users or groups, specified by Synapse IDs.
POST /userProfile Batch get UserGroupHeaders. This fetches information about a collection of users or groups, specified by Synapse IDs.
GET /userGroupHeaders Get Users and Groups that match the given prefix.
POST /userGroupHeaders/aliases Get Users and Groups that match the given list of aliases.
GET /userProfile/{profileId}/image Get the actual URL of the image file associated with a user's profile. Note: This call will result in a HTTP temporary redirect (307), to the actual f…
GET /userProfile/{profileId}/image/preview Get the actual URL of the image file associated with a user's profile. Note: This call will result in a HTTP temporary redirect (307), to the actual f…
POST /favorite/{id} Add an Entity as a Favorite of the caller.
DELETE /favorite/{id} Remove an Entity as a Favorite of the caller.
GET /favorite Get a paginated result that contains the caller's Favorites
GET /projects Get a paginated result that contains project headers and user activity (last access date) of the caller. The project list includes only those for whic…
GET /projects/user/{principalId} Get a paginated result that contains project headers and user activity (last access date) of the user specified by 'principalId'. The project list inc…

Verification Services

Identity verification is a service offered by the Synapse Access and Compliance Team to add an additional layer of legitimacy to a user account, beyond the basic requirements for creating an account in Synapse. After completing their user profile a user may submit a verification request, including supporting documentation. The ACT reviews the information then approves or rejects it. After approval, the ACT retains the authority to suspend verification of an account previously verified. Once rejected or suspended a user may create a new verification request.

Web Services
Resource Description
POST /verificationSubmission Create a VerficationSubmission. The content must match that of the user's profile. Notification is the request is sent to the Synapse Access and Compl…
POST /verificationSubmission/{id}/state Update the state of a verification submission. The allowed transitions are: Submitted -> Approved Submitted -> Rejected Approved -> Suspended Notifica…
DELETE /verificationSubmission/{id} Delete a verification submission by its ID. Note: This service may be called only by the original verification requestor.
GET /verificationSubmission List the verification submissions in the system. This service is available only to the Synapse Access and Compliance Team. Submissions may be filtered…

WikiPage Services

The Synapse WikiPage model object contains the data needed to render an end-user crafted web page. The Synapse Web Client will dynamically render a WikiPage into a combination of HTML, CSS and Javascript which is then finally rendered as a web page in the client's web browser.

These services provide support for creating, reading, updating, and deleting (CRUD) the WikiPage model objects.

WikiPages are composed of two major parts; the raw markdown text and a list of file attachments. For example, to embed an image from an end-user's machine into a WikiPage, the image file must first be uploaded to Synapse as FileHandle (see File Services). The FileHandle ID can then be added to a WikiPage.attachmentFileHandleIds list. See www.synapse.org for details on the supported markdown syntax.

WikiPages are not stand-alone objects, instead they are a component of another object such as an Entity or Evaluation. For example, when a WikiPage is created for an Entity, the Entity becomes the "owner" of the WikiPage. Access to the WikiPage is always tied to its owner. For example, to GET a WikiPage of an Entity, the caller must have read permission on the Entity.

To navigate the hierarchy of WikiPages associated with an owner use the GET /entity/{ownerId}/wikiheadertree method. The returned list of WikiHeaders can be used to construct a full wiki hierarchy tree for that owner.

Note: WikiPages can be nested to created a hierarchy of sub-pages. However, there can only be one root WikiPage per owner object, and all sub-pages are considered to be owned by the same object as the root page.

Web Services
Resource Description
POST /entity/{ownerId}/wiki Create a WikiPage with an Entity as an owner. Note: The caller must be granted the ACCESS_TYPE.CREATE permission on the owner. If the passed WikiPage …
POST /access_requirement/{ownerId}/wiki Create a WikiPage with an Access Requirement as an owner. Note: The caller must be granted the ACCESS_TYPE.CREATE permission on the owner. If the pass…
POST /evaluation/{ownerId}/wiki Create a WikiPage with an Evaluation as an owner. Note: The caller must be granted the ACCESS_TYPE.CREATE permission on the owner. If the passed WikiP…
GET /entity/{ownerId}/wiki Get the root WikiPage for an Entity. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner.
GET /evaluation/{ownerId}/wiki Get the root WikiPage for an Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner.
GET /entity/{ownerId}/wikikey Get the root WikiPageKey for an Entity. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner.
GET /evaluation/{ownerId}/wikikey Get the root WikiPageKey for an Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner.
GET /access_requirement/{ownerId}/wikikey Get the root WikiPageKey for an Access Requirement. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner.
GET /entity/{ownerId}/wiki/{wikiId} Get a specific WikiPage of of an Entity. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner.
GET /access_requirement/{ownerId}/wiki/{wikiId} Get a specific WikiPage of of an Access Requirement. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner.
GET /evaluation/{ownerId}/wiki/{wikiId} Get a specific WikiPage of of an Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner.
PUT /access_requirement/{ownerId}/wiki/{wikiId} Update a specific WikiPage of an Entity. Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Each time a Wiki…
PUT /entity/{ownerId}/wiki/{wikiId} Update a specific WikiPage of an Entity. Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Each time a Wiki…
PUT /evaluation/{ownerId}/wiki/{wikiId} Update a specific WikiPage of an Evaluation. Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Each time a …
DELETE /entity/{ownerId}/wiki/{wikiId} Delete a specific WikiPage of an Entity. Note: When a WikiPage is deleted, the delete will cascade to all children WikiPages (recursively) of the dele…
DELETE /evaluation/{ownerId}/wiki/{wikiId} Delete a specific WikiPage of an Evaluation. Note: When a WikiPage is deleted, the delete will cascade to all children WikiPages (recursively) of the …
GET /entity/{ownerId}/wikiheadertree Get a paginated list of all WikiHeaders that belong to the given owner Entity. The resulting list can be used to build a tree of the WikiPages for thi…
GET /evaluation/{ownerId}/wikiheadertree Get a paginated list of all WikiHeaders that belong to the given owner Evaluation. The resulting list can be used to build a tree of the WikiPages for…
GET /entity/{ownerId}/wiki/{wikiId}/attachmenthandles Get the list of FileHandles for all file attachments of a specific WikiPage for a given owning Entity. This list will include Previews if they exist a…
GET /evaluation/{ownerId}/wiki/{wikiId}/attachmenthandles Get the list of FileHandles for all file attachments of a specific WikiPage for a given owning Evaluation. This list will include Previews if they exi…
GET /entity/{ownerId}/wiki/{wikiId}/attachment Get a URL that can be used to download a file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (307), to…
GET /evaluation/{ownerId}/wiki/{wikiId}/attachment Get a URL that can be used to download a file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (307), to…
GET /entity/{ownerId}/wiki/{wikiId}/attachmentpreview Get a URL that can be used to download a preview file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (…
GET /evaluation/{ownerId}/wiki/{wikiId}/attachmentpreview Get a URL that can be used to download a preview file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (…

WikiPage Services 2

The Synapse V2WikiPage model object contains the data needed to render an end-user crafted web page. The Synapse Web Client will dynamically render a WikiPage into a combination of HTML, CSS and Javascript which is then finally rendered as a web page in the client's web browser.

These services provide support for creating, reading, updating, and deleting (CRUD) the WikiPage model objects.

WikiPages are composed of two major parts; a file that contains the markdown text and a list of file attachments. For example, to embed an image from an end-user's machine into a WikiPage, the image file must first be uploaded to Synapse as FileHandle (see File Services). The FileHandle ID can then be added to a WikiPage.attachmentFileHandleIds list. See www.synapse.org for details on the supported markdown syntax. The markdown text is similarly uploaded as a FileHandle and its FileHandle ID is tracked by the WikiPage.

WikiPages are not stand-alone objects, instead they are a component of another object such as an Entity or Evaluation. For example, when a WikiPage is created for an Entity, the Entity becomes the "owner" of the WikiPage. Access to the WikiPage is always tied to its owner. For example, to GET a WikiPage of an Entity, the caller must have read permission on the Entity.

To navigate the hierarchy of WikiPages associated with an owner use the GET /entity/{ownerId}/wikiheadertree2 method. The returned list of V2WikiHeaders can be used to construct a full wiki hierarchy tree for that owner.

To view a timeline of changes made to a WikiPage, use the GET/entity/{ownerId} /wiki2/{wikiId}/wikihistory method. The returned list of V2WikiHistorySnapshots contain information about who modified the WikiPage and when the changes were made.

Note: WikiPages can be nested to created a hierarchy of sub-pages. However, there can only be one root WikiPage per owner object, and all sub-pages are considered to be owned by the same object as the root page.

Web Services
Resource Description
POST /entity/{ownerId}/wiki2 Create a WikiPage with an Entity as an owner. Note: The caller must be granted the ACCESS_TYPE.CREATE permission on the owner. If the passed WikiPage …
POST /access_requirement/{ownerId}/wiki2 Create a WikiPage with an AccessRequirement as an owner. Note: The caller must be a member of the Synapse Access and Compliance Team. If the passed Wi…
POST /evaluation/{ownerId}/wiki2 Create a WikiPage with an Evaluation as an owner. Note: The caller must be granted the ACCESS_TYPE.CREATE permission on the owner. If the passed WikiP…
GET /entity/{ownerId}/wiki2 Get the root WikiPage for an Entity. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner.
GET /access_requirement/{ownerId}/wiki2 Get the root WikiPage for an AccessRequirement.
GET /evaluation/{ownerId}/wiki2 Get the root WikiPage for an Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner.
GET /entity/{ownerId}/wiki2/{wikiId} Get a specific WikiPage of an Entity. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner.
GET /access_requirement/{ownerId}/wiki2/{wikiId} Get a specific WikiPage of an Access Requirement.
GET /evaluation/{ownerId}/wiki2/{wikiId} Get a specific WikiPage of an Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ permission on the owner.
PUT /entity/{ownerId}/wiki2/{wikiId} Update a specific WikiPage of an Entity. This adds a new entry to the history of changes made to this specific WikiPage. Synapse employs an Optimistic…
PUT /entity/{ownerId}/wiki2orderhint Update an order hint that corresponds to the given owner Entity. Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent u…
PUT /access_requirement/{ownerId}/wiki2/{wikiId} Update a specific WikiPage of an Access Requirement. This adds a new entry to the history of changes made to this specific WikiPage. Synapse employs a…
PUT /evaluation/{ownerId}/wiki2/{wikiId} Update a specific WikiPage of an Evaluation. This adds a new entry to the history of changes made to this specific WikiPage. Synapse employs an Optimi…
PUT /entity/{ownerId}/wiki2/{wikiId}/{wikiVersion} For a specific WikiPage of an Entity, restore a version of the WikiPage's content. Synapse employs an Optimistic Concurrency Control (OCC) scheme to h…
PUT /access_requirement/{ownerId}/wiki2/{wikiId}/{wikiVersion} For a specific WikiPage of an Access Requirement, restore a version of the WikiPage's content. Synapse employs an Optimistic Concurrency Control (OCC)…
PUT /evaluation/{ownerId}/wiki2/{wikiId}/{wikiVersion} For a specific WikiPage of an Evaluation, restore a version of the WikiPage's content. Synapse employs an Optimistic Concurrency Control (OCC) scheme …
DELETE /entity/{ownerId}/wiki2/{wikiId} Delete a specific WikiPage of an Entity. Note: When a WikiPage is deleted, the delete will cascade to all children WikiPages (recursively) of the dele…
DELETE /access_requirement/{ownerId}/wiki2/{wikiId} Delete a specific WikiPage of an Access Requirement. Note: When a WikiPage is deleted, the delete will cascade to all children WikiPages (recursively)…
DELETE /evaluation/{ownerId}/wiki2/{wikiId} Delete a specific WikiPage of an Evaluation. Note: When a WikiPage is deleted, the delete will cascade to all children WikiPages (recursively) of the …
GET /entity/{ownerId}/wikiheadertree2 Get a paginated list of all V2WikiHeaders that belong to the given owner Entity. The resulting list can be used to build a tree of the WikiPages for t…
GET /entity/{ownerId}/wiki2orderhint Get an order hint that corresponds to the given owner Entity. The resulting hint can be used to establish a relative ordering for the subwikis in a tr…
GET /access_requirement/{ownerId}/wikiheadertree2 Get a paginated list of all V2WikiHeaders that belong to the given owner Access Requirement. The resulting list can be used to build a tree of the Wik…
GET /evaluation/{ownerId}/wikiheadertree2 Get a paginated list of all V2WikiHeaders that belong to the given owner Evaluation. The resulting list can be used to build a tree of the WikiPages f…
GET /entity/{ownerId}/wiki2/{wikiId}/wikihistory Get a paginated list of all V2WikiHistorySnapshot that belong to a specific WikiPage, which belong to the given owner Entity. The resulting list can b…
GET /access_requirement/{ownerId}/wiki2/{wikiId}/wikihistory Get a paginated list of all V2WikiHistorySnapshot that belong to a specific WikiPage, which belong to the given owner Access Requirement. The resultin…
GET /evaluation/{ownerId}/wiki2/{wikiId}/wikihistory Get a paginated list of all V2WikiHistorySnapshot that belong to a specific WikiPage, which belong to the given owner Evaluation. The resulting list c…
GET /entity/{ownerId}/wiki2/{wikiId}/attachmenthandles Get the list of FileHandles for all file attachments of a specific WikiPage for a given owning Entity. This list will include Previews if they exist a…
GET /access_requirement/{ownerId}/wiki2/{wikiId}/attachmenthandles Get the list of FileHandles for all file attachments of a specific WikiPage for a given owning Access Requirement. This list will include Previews if …
GET /evaluation/{ownerId}/wiki2/{wikiId}/attachmenthandles Get the list of FileHandles for all file attachments of a specific WikiPage for a given owning Evaluation. This list will include Previews if they exi…
GET /entity/{ownerId}/wiki2/{wikiId}/attachment Get a URL that can be used to download a file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (307), to…
GET /access_requirement/{ownerId}/wiki2/{wikiId}/attachment Get a URL that can be used to download a file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (307), to…
GET /evaluation/{ownerId}/wiki2/{wikiId}/attachment Get a URL that can be used to download a file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (307), to…
GET /entity/{ownerId}/wiki2/{wikiId}/attachmentpreview Get a URL that can be used to download a preview file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (…
GET /access_requirement/{ownerId}/wiki2/{wikiId}/attachmentpreview Get a URL that can be used to download a preview file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (…
GET /evaluation/{ownerId}/wiki2/{wikiId}/attachmentpreview Get a URL that can be used to download a preview file for a given WikiPage file attachment. Note: This call will result in a HTTP temporary redirect (…
GET /entity/{ownerId}/wiki2/{wikiId}/markdown Get a URL that can be used to download the markdown file for a given WikiPage. Note: This call will result in a HTTP temporary redirect (307), to the …
GET /access_requirement/{ownerId}/wiki2/{wikiId}/markdown Get a URL that can be used to download the markdown file for a given WikiPage. Note: This call will result in a HTTP temporary redirect (307), to the …
GET /evaluation/{ownerId}/wiki2/{wikiId}/markdown Get a URL that can be used to download the markdown file for a given WikiPage. Note: This call will result in a HTTP temporary redirect (307), to the …