Synapse REST API

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 access type.
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 access type.
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…

Agent Chat Services

The Synapse chat services allow the user to chat with a 'bot' (agent) that has access to Synapse data. By default, Synapse provides a 'baseline' agent that has basic access to all of the supported Synapse action group functions and knowledge bases. Sage authorized collaborators can create their own agents that can also utilize the same action groups and knowledge bases used by the baseline agent. The collaborator's agent can then be used to override the baseline agent for chat sessions.

To get started, the first step is to create a new session by calling: POST /agent/session. You will need the sessionId from the resulting AgentSession. The sessionId uniquely identifies a single conversation between the user and the agent. Specifically, the session contains user's chat requests, agent responses and all of the data gathered by the agent to meet user requests. The session data is the context provided to the Large Language Model (LLM) used by the agent. Only the user that create a session will have access to its data and be able to use it for an agent conversation.

The user's conversation with an agent is a series of asynchronous jobs under the provided sessionId, where each job is started by providing the user's prompt to the agent. The job's response will then include the agent's response to the user's prompt. Use: POST /agent/chat/async/start to start a chat job and GET /agent/chat/async/get/{asyncToken} to get the job's results.

Web Services

Resource	Description
POST /agent/session	Start a new chat session. Each chat session request must include an AgentAccessLevel that defines what level of data access the agent will given durin…
GET /agent/session/{sessionId}	Get the agent session using its session id.
PUT /agent/session/{sessionId}	Update the access level of an existing agent session. Only the user that started the session can change its access level.
POST /agent/chat/async/start	Start an asynchronous job to exchange a single prompt from the user in the request. The agent's response to this prompt can be retrieved by calling: G…
GET /agent/chat/async/get/{asyncToken}	Get the agent's response to a user's prompt started by calling: POST /agent/chat/async/start Only the user that started the job may get the job's resu…
POST /agent/chat/trace/{jobId}	Get a single page of trace events associated with an AgentChatRequest. The resulting TraceEvents will be ordered by timestamp ascending. Note: The Age…
PUT /agent/registration	Create or Get the AgentRegistration that matches the provided request. This call is idempotent. If a matching AgentRegistration already exists, then i…
GET /agent/registration/{agentRegistrationId}	Get the AgentRegistration given its id.

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 /termsOfUse2/info	Get the information about the latest version of the terms of service together with the requirements in effect.
GET /termsOfUse2/status
PUT /termsOfUse2/requirements	Updates the terms of service requirements. Only an administrator can perform this operation.
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.
DELETE /sessionAccessToken	Revokes the access token used to perform the request. E.g Can be used to logout the current user.
DELETE /user/{targetUserId}/sessionAccessToken/all	Revokes any access token issued for the given user. If the target user id does not match the user in the access token used to perform the request the …

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:

POST /2fa/enroll: Generates a shared secret that is added to the user authenticator application
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…
POST /2fa/reset	Initiates the reset of two factor authentication, sending a notification to the user with a signed token. The request can be performed using the twoFa…
POST /2fa/disable	Disables two factor authentication for the user encoded in the signed token received by email following a call to the POST /2fa/reset endpoint. The re…

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 /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.
PUT /user/{id}/revokeCertification	Revokes the certification for the user. Only an ACT member can perform this operation.

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
POST /restrictionInformation/batch	Retrieve restriction information on a batch of restrictable object, limited to a maxiumum of 50 object ids
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:

Get a pre-signed URL to upload the part to using: POST /file/multipart/{uploadId}/presigned/url/batch
Upload the part to the pre-signed URL using HTTPs PUT
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:

Get the part copy pre-signed URLs using: POST /file/multipart/{uploadId}/presigned/url/batch
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.
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.
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:

UploadDestinationListSetting: Used to customize the storage location for files in a project

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.

Project Storage Services

Services to manage project storage usage and limits.

Web Services

Resource	Description
GET /project/{projectId}/storage/usage	Get the current project usage and limits for the project with the given id.
PUT /project/{projectId}/storage/limit	Allows to set a limit on a project for the storage location provided in the request body. If the maxAllowedFileBytes property in the request is null, …

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…

Webhook Services

Provides APIs to manage webhooks that are triggered by synapse events.

A webhook can specify the id of a synapse entity to receive events for. For entities that represent a container (folder and project), matching events are published to the webhook endpoint for any entity in their hierarchy.

Before events are published to the endpoint, the webhook needs to be verified. A special request is sent to the webhook endpoint containing a verification code that can be submitted in the body of the POST /webhook/{webhookId}/verify request.

Request Format

There are two types of requests that can be sent to an endpoint:

WebhookVerificationMessage: Sent when a webhook is created or when its endpoint is updated that contains the verification code used to verify the webhook.
WebhookSynapseEventMessage: Sent when a synapse event that match the webhook entity is generated in the backend.

Each HTTP request will contain the following custom headers:

X-Syn-Webhook-Id: The id of the webhook
X-Syn-Webhook-Message-Type: The type of message body, either Verification or SynapseEvent
X-Syn-Webhook-Message-Id: A unique id for the message
X-Syn-Webhook-Owner-Id: The id of the user that created the webhook

And the following standard headers:

Content-Type: Always application/json
User-Agent: Set with the prefix Synapse-Webhook/, followed by the synapse stack version
Authorization: Set with the Bearer prefix, followed by an authentication token (See below)

Request Handling

A request to an endpoint is sent at least once and retried for a maximum of 3 times. The endpoint needs to provide a response within 2 seconds in order for the request to be considered successful, otherwise the request is retried. Valid HTTP response codes are:

200 (OK)
201 (CREATED)
202 (ACCEPTED)
204 (NO CONTENT)

The following response codes are considered for retrying:

429 (TOO MANY REQUESTS)
500 (INTERNAL SERVER ERROR)
502 (BAD GATEWAY)
503 (SERVICE UNAVAILABLE)
504 (GATEWAY TIMEOUT)

Any other response code is considered a failed delivery and won't be retried. If a webhook endpoint consistently fails to respond to requests, it will eventually be disabled and the verification status of the webhook will be set to REVOKED and will need to be re-verified.

Limits

Each user is limited to a maximum of 25 webhooks. The webhook endpoint is checked against a white list of allowed domain patterns, currently only the AWS Api Gateway execute-api is allowed. For adding a new domain exception you can submit a request to the Synapse Service Desk.

Authentication

By default each request includes a signed JSON Web Token (JWT) in the Authorization header as a bearer token. The token is signed with a JSON Web Key (JWK) and can be verified using the public JWK id specified in the header of the JWT. The public keys are published under the "well-known" discovery document of the issuer (See below).

The JWT will contain a set of standard claims that can be used to validate the token:

iss: The issuer of the token is set to https://repo-prod.prod.sagebase.org/auth/v1. The openid discovery document (https://repo-prod.prod.sagebase.org/auth/v1/.well-known/openid-configuration) can be used to get information about the JWKs
aud: The audience contains the id of the user that owns the webhook
iat: The timestamp when the token was generated
exp: The expiration time of the token, each token is valid for 30 seconds.

To verify the integrity of the message, the MD5 of the request body is included under the custom claim message_md5 and can be verified against the md5 of the request body once the JWT is verified.

Web Services

Resource	Description
POST /webhook	Create a new webhook. A user can create a maximum of 25 webhooks. Once created the webhook needs to be verified using the POST /webhook/{webhookId}/ve…
GET /webhook/{webhookId}	Get the webhook with the provided id, the caller must be the creator of the webhook.
POST /webhook/list	Get the list of webhooks for the caller.
PUT /webhook/{webhookId}	Update the webhook with the given id, the caller must be the creator of the webhook. If the endpoint is modified the webhook verification status will …
POST /webhook/{webhookId}/verify	Verifies a webhook with the verificationCode received by the endpoint in a WebhookVerificationMessage request. The caller must be the creator of the w…
PUT /webhook/{webhookId}/verificationCode	When the verification fails or if a verification code is lost or wasn't received, this API allows to sent a new verification code to the webhook endpo…
DELETE /webhook/{webhookId}	Deletes the webhook with the given id, the caller must be the creator of the webhook.

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.

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.

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 …

Table of Contents

Access Approval Services

Web Services

Access Requirement Services

Web Services

Activity Services

Used & Generated By

Access Control for Activities

Web Services

Agent Chat Services

Web Services

Asynchronous Job Services

Web Services

Authentication Services

Web Services

Authentication Services (2FA)

Web Services

Certified User Services

Web Services

Challenge Services

Web Services

DOI Services

Web Services

Data Access Services

Web Services

Discussion Services

Web Services

Docker Authorization Services

Web Services

Docker Commit Services

Web Services

Docker Registry Event Services

Web Services

Download List Services

Web Services

Drs Services

Web Services

Entity Bundle Services V2

Web Services

Entity Services

Annotations

Authorization

Versions

JSON Schemas

Web Services

Evaluation Services

Web Services

File Services

Web Services

Form Services

Web Services

JSON Schema Services

Web Services

Log Service

Web Services

Membership Invitation Services

Web Services

Membership Request Services

Web Services

Message Services

Web Services

OpenID Connect Services

Web Services

Principal Services

Web Services

Project Settings Services

Web Services

Project Storage Services

Web Services

Recycle Bin Services

Web Services

Search Services

Web Services

Statistics Services

Web Services

Storage Report Services

Web Services

Subscription Services

Web Services

Table Services