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}
GET /entity/{id}/accessApproval Retrieve the Access Approvals for the given Entity. This service is only available to the ACT.
GET /team/{id}/accessApproval Retrieve the Access Approvals for the given Team. This service is only available to the ACT.
DELETE /accessApproval/{approvalId} Delete a selected Access Approval. This service is only available to the ACT.
DELETE /accessApproval Delete Access Approval. This service is only available to the ACT.

Access Requirement Services

These services manage the Access Requirements/Restrictions (ARs) which may be placed on Entities, Evaluation queues, 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, Evaluation queue, 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, Evaluation queue, 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.

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.
GET /asynchronous/job/{jobId}/cancel Once a job is launched it can be cancelled if the job is set up to be cancelable.

Authentication Services

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

Synapse currently supports four modes of authentication:

  • username and password
  • OpenID from Google
  • session token
  • API key

Only the session token or API key can be used to authenticate the user outside of the authentication services. Authentication via a username and password, or via OpenID, will allow the user to retrieve a session token and/or API key for use in other requests.

Web Services
Resource Description
POST /session Retrieve a session token that will be usable for 24 hours or until invalidated. The user must accept the terms of use before a session token is issued…
POST /login Retrieve a session token that will be usable for 24 hours or until invalidated. The user must accept the terms of use before a session token is issued…
PUT /session Refresh a session token to render it usable for another 24 hours.
DELETE /session Deauthenticate a session token. This will sign out all active sessions using the session token.
POST /user/password/email Sends an email for setting a user's password. The query parameter domain may be appended to this URI. If absent or set to "synapse", the service will …
POST /user/password Change the current authenticated user's password.
POST /termsOfUse Identifies a user by a session 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/session 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 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.

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 /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 /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 /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 /user/{id}/certificationStatus

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
PUT /entity/{id}/doi Creates a DOI for the specified entity. The DOI will associated with the most recent version where applicable.
PUT /entity/{id}/version/{versionNumber}/doi Creates a DOI for the specified entity version.
GET /entity/{id}/doi Gets the DOI of the specified entity.
GET /entity/{id}/version/{versionNumber}/doi Gets the DOI of the specified entity version.

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. Only ACT member can perform this action.
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.

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 belongs to projects user can view and references the …
GET /forum/{forumId}/moderators Returns a page of moderators for a given forum ID. Target users: anyone who has READ permission to the project.

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

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. Commits for both managed and external/unmanaged repositories may be retrieved using the 'listDockerCommits' 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}/dockerCommit List the commits (tag/digest pairs) for the given Docker repository. Only the most recent digest for each tag is returned since, following Docker's co…

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 …

Entity Bundle Services

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.

One of the request parameters for an EntityBundle is an integer "mask" or "partsMask". This integer is used as a bit-string of flags to specify which parts to include in the EntityBundle. As of this writing, the mask is defined as follows:

  • Entity (Entity) = 0x1
  • Annotations (Annotations) = 0x2
  • Permissions (UserEntityPermissions) = 0x4
  • Entity Path (EntityPath) = 0x8
  • Entity References (List<EntityHeader>) = 0x10
  • HasChildren (Boolean) = 0x20
  • ACL (AccessControlList) = 0x40
  • Access Requirements (List<AccessRequirement>) = 0x200
  • Unmet Access Requirements (List<AccessRequirement>) = 0x400
  • File Handles (List<FileHandle>) = 0x800
  • TableEntity Metadata (TableBundle) = 0x1000

For example, if the Entity and its Annotations are desired, the request mask value should be 0x1 + 0x2 = 0x3.

Web Services
Resource Description
GET /entity/{id}/bundle Get an entity and related data with a single GET. Note that childCount is calculated in the QueryController.
GET /entity/{id}/version/{versionNumber}/bundle Get an entity at a specific version and its related data with a single GET. Note that childCount is calculated in the QueryController.
POST /entity/bundle 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}/bundle Update an entity and associated components with a single POST. 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 or Records (coming soon) that reside within Folders or directly within Projects. All these objects (Projects, Folders, FileEntities, and Records) 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.

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

Annotations

An Entity can be annotated using the PUT /entity/{id}/annotations method. Each annotation is a key-value pair. The GET /entity/{id}/annotations 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.

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 a new version of the FileEntity is automatically created. The file history an 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.

Note: Only the File and Annotations of an Entity are include 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

Web Services
Resource Description
POST /entity Create a new Entity. This method is used to create Projects, Folders, FileEntities and Records (coming soon). The passed request body should contain t…
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…
DELETE /entity/{id} Delete an entity using its ID. Note: To delete an Entity the caller must be granted the ACCESS_TYPE.DELETE on the Entity.
GET /entity/{id}/annotations Get the annotations for an entity. Note: The caller must be granted the ACCESS_TYPE.READ on the Entity, to get its annotations.
PUT /entity/{id}/annotations Update an entities 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}/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 /entity/{id}/version/{versionNumber}/annotations Get an Entity's annotations for a specific version of a FileEntity.
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 genratedBy relationship for the current version of an Entity.
DELETE /entity/{id}/generatedBy Deletes the genratedBy 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 all FileEntities whose file's MD5 is the same as the specified MD5 string.
GET /entity/alias/{alias} Lookup an Entity ID using an alias.
POST /entity/children Get a page of children for a given parent ID.
POST /entity/child Retrieve an entityId for a given parent ID and entity name.

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.

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 caller must be granted the ACCESS_TYPE.READ on the specified Evaluations.
GET /evaluation Gets a collection of Evaluations, within a given range. Note: The response will contain only those Evaluations on which the caller must is granted the…
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. The passed request body should contain the following fields: evaluationId - The ID of the Evaluation to which this Submission be…
POST /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. This service is intended to only be used by ChallengesInfrastructure service account. Note…
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.
POST /evaluation/acl Creates a new access control list (ACL) for an evaluation. The ACL to be created should have the ID of the evaluation. The user must be an owner of th…
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…
DELETE /evaluation/{evalId}/acl Deletes the ACL (access control list) of the specified evaluation. The user should have the proper permissions to delete the ACL.
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.
GET /evaluation/submission/query Executes a user-defined query over the Submissions of a specific Evaluation. Queries have the following form: SELECT FROM evaluation_ [WH…
PUT /evaluation/submission/{subId}/cancellation User requests to cancel their submission. Only the user who submitted a submission can make this request.

File Services

Files in Synapse are repressed with a FileHandle object. There are currently three concrete implementations of FileHandle: ExternalFileHandle, S3FileHandle, PreviewFileHandle.

ExternalFileHandle

An external file handle is used to represent an external URL. Synapse will attempt to generate a preview for any external URL that can be publicly read. The resulting preview file will be stored in Synapse and represented with a PrevewFileHandle. The creator of the ExternalFileHandle will be listed as the creator of the preview.

S3FileHandle

When a file is stored in Synapse, by default it is stored in Amazon's S3. The S3FileHandle captures the extra information about the S3 file. Just like ExternalFileHandles, Synapse will attempt to automatically create a preview of all S3FileHandles.

PreviewFileHandle

When Synapse creates a preview file for either an ExternalFileHandle or an S3FileHandle, the resulting preview file will be stored in S3 and be assigned a PreviewFileHandle. Currently, Synapse will generate previews based on the original file's contentType (see: Internet Media Type).

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 mutli-part upload 1 MB is defined as 1024*1024 bytes

The first task in mutli-part upload is choosing a part size. The minimum part size is 5 MB (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 the 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 mutli-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.

Associating FileHandles with Synapse objects

Currently, FileHandles can be associated with a FileEntity and a WikiPage. For more information see the following:

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 PreviewFileHandle.
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/proxy Create a ProxyFileHandle to represent a File in a user's file repository. All ProxyFileHandle must have a storageLocationId set to an existing ProxySt…
GET /entity/{id}/uploadDestinationLocations Get the upload destination locations for this parent entity. This will return a list of at least one destination location. The first destination in th…
GET /entity/{id}/uploadDestination/{storageLocationId} Get the upload destinations for this storage location id. This will always return an upload destination
GET /entity/{id}/uploadDestination Get the default upload destinations for this entity id. This will always return an upload destination
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 of a file. By default this method is idempotent, so subsequent calls will simply return the current status of the …
POST /file/multipart/{uploadId}/presigned/url/batch Get a batch of pre-signed URLS that should be used to upload file parts. Each part will require a unique pre-signed URL. The client is expected to PUT…
PUT /file/multipart/{uploadId}/add/{partNumber} After the contents of part have been upload (PUT to a pre-signed URL) this method is used to added the part to the multipart upload. If the upload par…
PUT /file/multipart/{uploadId}/complete After all of the parts have been upload and added successfully, this method is called to complete the upload resulting in the creation of a new file h…
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…

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. The Team and invitee must be specified. Optionally, the creator may include an invitation message and/or expiration da…
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 specified Team to make this request.
DELETE /membershipInvitation/{id} Delete an invitation Note: The client must be an administrator of the Team referenced by the invitation to make this request.

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. The Team must be specified. Optionally, the creator may include a message and/or expiration date for the request. If no e…
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.

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 /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

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. A session token is not required for this call. Each value of each AliasType must ha…
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 /account 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

Web Services
Resource Description
GET /projectSettings/{id}
GET /projectSettings/{projectId}/type/{type}
POST /projectSettings
PUT /projectSettings
DELETE /projectSettings/{id}
POST /storageLocation
GET /storageLocation
GET /storageLocation/{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} Purges the specified entity from the trash can. Once purging is done, the entity will be permanently deleted from the system.
PUT /trashcan/purge Purges everything in the trash can for the current user. Once purging is done, items in the trash can will permanently removed from the system.
GET /admin/trashcan/view For administrators to view the entire trash can.
PUT /admin/trashcan/purge For administrators to purge the entire trash can.
PUT /admin/trashcan/purgeleaves For administrators to purge trash items with no children trash items that are more than some days old

Search Services

CloudSearch search controller. It currently offers two methods:

  1. '/search' appends a authorization filter to the user's search and reformats the result into a Synapse model object

Web Services
Resource Description
POST /search

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
GET /object/{objectId}/{objectType}/etag This API is used to retrieve the etag of a subscribable object. The client could use this method to check if an object has changed.
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/append/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/append/async/start.

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

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.
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/{viewtype} Get the list of default ColumnModels that are available for a ViewType .
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/append/async/start Asynchronously start a job to append row data to a table. This method is used to both add and update rows to a TableEntity. This method accepts either…
GET /entity/{id}/table/append/async/get/{asyncToken} Asynchronously get the results of a PartialRowSet update to a table started with POST /entity/{id}/table/partial/async/start Note: When the result is …
POST /entity/{id}/table/deleteRows This method is used to delete rows in a TableEntity. The rows in the passed in RowSelection will be deleted if they exist (a 400 will be returned if a…
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/query/nextPage/async/start Asynchronously get a next page of a query. Use the returned job id and POST /entity/{id}/table/query/nextPage/async/start to get the results of the qu…
GET /entity/{id}/table/query/nextPage/async/get/{asyncToken} Asynchronously get the results of a nextPage query started with POST /entity/{id}/table/query/nextPage/async/start Note: When the result is not ready …
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
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 Get the possible ColumnModel definitions based on annotation within a given scope.

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.
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}
GET /team/{id} Retrieve the metadata for a specified Team.
GET /team/{id}/icon Retrieve the download URL for the Team icon, 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. Invalid IDs in the list are ignored: The results list is simply smaller than the …
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 by name.
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/{type} Get a paginated result that contains the project headers from a user. The list is ordered by most recent interacted with project first
GET /projects/{type}/team/{teamId} Same as getProjects, but has team parameter
GET /projects/{type}/user/{principalId} Same as getProjects, but has other user id parameter

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 …