SharpED for developers

Integrate SharpED density-map restoration into your own crystallographic software or automated workflow. The API accepts an XPLOR map, places the request in a processing queue and returns the restored map when the job is complete.

Get an API token Download the Python example

How the API works

1

Discover models

Ask the server for the currently available models and its default choice.

2

Submit a map

Upload an XPLOR map together with the element list, output sampling and model name.

3

Monitor the job

Use the returned job token to poll the queue until processing is complete.

4

Download the result

Download the restored density map and continue with your own workflow.

1. Get an API token

  1. Register or sign in at sharped.fzu.cz/login. Authentication is handled through the Jana2020 login page.
  2. Open the SharpED application page.
  3. Generate an API token and copy it to a secure location.
  4. Use this value as SHARPED_API_TOKEN in your application.
Keep your token private. Do not place it directly in public source code, commit it to a repository or expose it in client-side JavaScript.

 

Set the token as an environment variable

Windows PowerShell:

$env:SHARPED_API_TOKEN = "your-token"

Linux and macOS:

export SHARPED_API_TOKEN="your-token"

2. Discover the available models

Model names can change as new SharpED models are deployed. Query the model endpoint instead of hard-coding a model name. This request does not require authentication.

GET https://jana.fzu.cz/sharp-ed/models

Example using cURL:

curl https://jana.fzu.cz/sharp-ed/models

The response contains the server default and the list of available model names:

{
  "default": "current-default-model",
  "models": ["current-default-model", "another-model"]
}

3. Submit a job

Send the input map and processing parameters as a multipart/form-data request. Authenticate with your SharpED API token in the HTTP Authorization header.

POST https://jana.fzu.cz/api/user/sharp-ed/upload
Authorization: Bearer <API_TOKEN>

Example using cURL:

curl -X POST "https://jana.fzu.cz/api/user/sharp-ed/upload" \
  -H "Authorization: Bearer $SHARPED_API_TOKEN" \
  -F "file=@input.xplor" \
  -F "elements=C N O" \
  -F "outres=0.2" \
  -F "model=current-default-model"

Upload fields

Field Description Example
file Input electron-density map in XPLOR format. input.xplor
elements Space-separated chemical elements expected in the structure. C N O Zn
outres Requested sampling of the output map in ångströms. 0.2
model Exact model name returned by the model endpoint. current-default-model

A successful response contains a job token and may also include a job ID and status URL:

{
  "success": true,
  "job_id": 123,
  "token": "job-token",
  "status_url": "/api/user/sharp-ed/status/job-token"
}

4. Monitor the processing queue

Poll the returned status_url. If it is not included in the upload response, construct the URL from the returned job token. Use the same user API token for authentication.

GET https://jana.fzu.cz/api/user/sharp-ed/status/<JOB_TOKEN>
Authorization: Bearer <API_TOKEN>

While the status is processing, wait briefly and request the status again. Continue when the status becomes completed. If the status is failed, show the returned error message and stop the workflow.

5. Download the restored map

After the job is complete, download the result using the job token. The same SharpED user API token is sent in the authorization header.

GET https://jana.fzu.cz/api/user/sharp-ed/download/<JOB_TOKEN>
Authorization: Bearer <API_TOKEN>

Save the binary response as an XPLOR map and verify that the downloaded file is not empty before continuing your workflow.

Python quick start

The complete example discovers the current default model, uploads input.xplor, waits for processing and saves the result as restored.xplor.

  1. Install Python 3 and the Requests package: python -m pip install requests
  2. Set the SHARPED_API_TOKEN environment variable.
  3. Place input.xplor next to the script.
  4. Run python sharped_api_example.py.

Download sharped_api_example.py

API reference

Base URL: https://jana.fzu.cz

Method Endpoint Authentication Purpose
GET /sharp-ed/models None List the current models and server default.
POST /api/user/sharp-ed/upload Bearer API token Upload a map and create a queued job.
GET /api/user/sharp-ed/status/{job_token} Bearer API token Read the current job status.
GET /api/user/sharp-ed/download/{job_token} Bearer API token Download the completed output map.

Good practice

  • Query the model endpoint so that your integration follows the current server default.
  • Use a reasonable interval between status requests; the example waits two seconds.
  • The current public server accepts XPLOR map uploads up to 100 MB.
  • Set sufficiently long HTTP timeouts for large map uploads and processing jobs.
  • SharpED output is a machine-learning reconstruction. Inspect and validate the restored density in its crystallographic context.

Reference implementation

Phase Studio is an open-source application that integrates the SharpED API into a crystallographic workflow. Its source code provides a more extensive client implementation, including additional validation and error handling.