Skip to main content
Prophy API
API reference
Webhooks
MCP

Quickstart

Upload your first manuscript and get reviewer candidates in a few minutes. You need a terminal with curl.

1. Get your API Key

Open the Integrations dashboard, then reveal and copy the API Key on the API Keys page. The dashboard is available to users with the Integrations admin permission.

2. Upload a manuscript

Save the key in an environment variable: run this command, paste the key and press Enter. The key isn't shown on the screen and doesn't get into your shell history. 

read -s PROPHY_API_KEY && export PROPHY_API_KEY

Then send a manuscript to a test folder. The folder is created on the first upload. 

curl --http1.1 -X POST "http://prophy.eismea.eu/api/external/proposal/" \
-H "X-ApiKey: $PROPHY_API_KEY" \
-F "folder=API test" \
-F "origin_id=quickstart-1" \
-F "title=Features in the Standard Model diphoton background" \
-F "abstract=We argue that the electromagnetic decays of energetic unflavoured neutral mesons, notably η, mis-identified as single photons due to granularity of the electromagnetic calorimeter might create bump-like features in the diphoton invariant mass spectrum at different energies, including 750 GeV." \
-F "authors_count=2" \
-F "author1_name=Kyrylo Bondarenko" \
-F "author2_name=Alexey Boyarsky"

origin_id is the manuscript ID in your system, and authors_count must match the number of authorN_name fields. All parameters are described in Manuscript upload.

Add the manuscript file

In a real integration, send the manuscript file too: Prophy then searches by the full text, not only by the title and abstract. Add the source_file field with a PDF or DOCX file at the end of the request: 

...
-F "author2_name=Alexey Boyarsky" \
-F "source_file=@manuscript.pdf"

curl reads manuscript.pdf from the folder where you run the command, so run it next to your file or give the full path, for example @/home/me/manuscript.pdf.

3. Read the response

The response comes back in the same request. A shortened example: 

{
  "version": 8,
  "manuscript_id": 57502,
  "origin_id": "quickstart-1",
  "candidates": [
    {
      "name": "Stefano Moretti",
      "author_id": 4935435,
      "affiliation": "Uppsala University, Uppsala, Sweden",
      "url": "http://prophy.eismea.eu/author/4935435/Stefano-Moretti/",
      ...
    },
    ...
  ],
  "debug_info": {
    "parsed_text_len": 31254,
    "authors_info": {"authors_count": 2, ...},
    ...
  },
  ...
}
  • version — the response version. See Integration guide → API versions.
  • manuscript_id — the manuscript ID in Prophy.
  • origin_id — your ID, returned as is.
  • candidates — reviewer candidates. Show them to the editor.
  • author_id — the candidate's author ID in Prophy.
  • debug_info — what Prophy found in the file. Include it when you contact support about a manuscript.

If the request fails

Errors come back as JSON with an error message, for example: 

{
  "error": "Wrong API key"
}
  • 401 — the X-ApiKey header is missing or the key is wrong.
  • 400 — a required field is missing or authors_count doesn't match the authors. The message lists what Prophy received.

For other problems, see Troubleshooting.

Upload it again

When the manuscript data changes in your system, send the request again with the same origin_id. Prophy overwrites the manuscript with the new data instead of creating a new one, keeps the same manuscript_id and returns new candidates.

Next steps