{
  "openapi": "3.1.1",
  "info": {
    "title": "Scholvet API",
    "description": "Reviewer search and invitations for journal systems. Send the journal's key in the X-Api-Key header. Guide: https://developers.scholvet.com",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://api.scholvet.com",
      "description": "Live"
    }
  ],
  "paths": {
    "/v1/me": {
      "get": {
        "tags": [
          "v1"
        ],
        "summary": "Returns the journal the API key belongs to.",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "tags": [
          "v1"
        ],
        "summary": "Quota of the journal's institution account: accepted invitations in the current period.",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/reviewer-searches": {
      "post": {
        "tags": [
          "v1"
        ],
        "summary": "Finds matching reviewers for an article. Returns pseudonymous codes and scores only.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReviewerSearchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/invitations": {
      "post": {
        "tags": [
          "v1"
        ],
        "summary": "Invites a reviewer from a search result. The reviewer is notified and answers on the platform.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInvitationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "get": {
        "tags": [
          "v1"
        ],
        "summary": "Invitations of this journal for one article (articleRef), newest first.",
        "parameters": [
          {
            "name": "articleRef",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/invitations/{id}": {
      "get": {
        "tags": [
          "v1"
        ],
        "summary": "Invitation status. Reviewer identity is included once the reviewer has accepted.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/invitations/{id}/cancel": {
      "post": {
        "tags": [
          "v1"
        ],
        "summary": "Withdraws a pending or accepted invitation.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/invitations/{id}/completion": {
      "post": {
        "tags": [
          "v1"
        ],
        "summary": "Confirms the review was completed. Points are awarded to the reviewer only through this call.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompleteInvitationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/reviewers": {
      "post": {
        "tags": [
          "v1"
        ],
        "summary": "Registers a reviewer the journal added by hand or the authors suggested. The person is informed by e-mail.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NominateReviewerRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AuthorInput": {
        "required": [
          "orcid",
          "institution",
          "rorId"
        ],
        "type": "object",
        "properties": {
          "orcid": {
            "maxLength": 40,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "institution": {
            "maxLength": 300,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "rorId": {
            "maxLength": 60,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "CompletedReviewInput": {
        "required": [
          "completedOn",
          "articleRef"
        ],
        "type": "object",
        "properties": {
          "completedOn": {
            "type": "string",
            "format": "date-time"
          },
          "articleRef": {
            "maxLength": 80,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "CompleteInvitationRequest": {
        "required": [
          "accepted",
          "qualityRating",
          "completedAt"
        ],
        "type": "object",
        "properties": {
          "accepted": {
            "type": "boolean"
          },
          "qualityRating": {
            "maximum": 5,
            "minimum": 1,
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "null",
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "completedAt": {
            "type": [
              "null",
              "string"
            ],
            "format": "date-time"
          }
        }
      },
      "CreateInvitationRequest": {
        "required": [
          "searchId",
          "reviewerCode",
          "externalRef",
          "articleTitle",
          "articleAbstract",
          "message",
          "respondByDays",
          "reviewDays"
        ],
        "type": "object",
        "properties": {
          "searchId": {
            "type": "string",
            "format": "uuid"
          },
          "reviewerCode": {
            "maxLength": 16,
            "minLength": 0,
            "type": "string"
          },
          "externalRef": {
            "maxLength": 80,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "articleTitle": {
            "maxLength": 600,
            "minLength": 0,
            "type": "string"
          },
          "articleAbstract": {
            "maxLength": 4000,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "message": {
            "maxLength": 2000,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "respondByDays": {
            "maximum": 30,
            "minimum": 1,
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "null",
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "reviewDays": {
            "maximum": 90,
            "minimum": 1,
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "null",
              "integer",
              "string"
            ],
            "format": "int32"
          }
        }
      },
      "NominateReviewerRequest": {
        "required": [
          "fullName",
          "email",
          "orcid",
          "academicTitle",
          "institution",
          "rorId",
          "source",
          "articleRef",
          "keywords",
          "culture"
        ],
        "type": "object",
        "properties": {
          "fullName": {
            "maxLength": 200,
            "minLength": 0,
            "type": "string"
          },
          "email": {
            "maxLength": 256,
            "minLength": 0,
            "type": "string"
          },
          "orcid": {
            "maxLength": 40,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "academicTitle": {
            "maxLength": 80,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "institution": {
            "maxLength": 300,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "rorId": {
            "maxLength": 60,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "source": {
            "pattern": "^(journal|author)$",
            "type": "string"
          },
          "articleRef": {
            "maxLength": 80,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "keywords": {
            "maxItems": 30,
            "type": [
              "null",
              "array"
            ],
            "items": {
              "type": "string"
            }
          },
          "culture": {
            "pattern": "^(tr|en)$",
            "type": [
              "null",
              "string"
            ]
          },
          "keywordYear": {
            "maximum": 2100,
            "minimum": 1950,
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "null",
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "completedReviews": {
            "maxItems": 200,
            "type": [
              "null",
              "array"
            ],
            "items": {
              "$ref": "#/components/schemas/CompletedReviewInput"
            }
          }
        }
      },
      "ReviewerSearchRequest": {
        "required": [
          "articleRef",
          "title",
          "abstract",
          "keywords",
          "authors",
          "maxResults"
        ],
        "type": "object",
        "properties": {
          "articleRef": {
            "maxLength": 80,
            "minLength": 0,
            "type": "string"
          },
          "title": {
            "maxLength": 600,
            "minLength": 0,
            "type": "string"
          },
          "abstract": {
            "maxLength": 6000,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "keywords": {
            "maxItems": 30,
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "authors": {
            "maxItems": 50,
            "type": [
              "null",
              "array"
            ],
            "items": {
              "$ref": "#/components/schemas/AuthorInput"
            }
          },
          "maxResults": {
            "maximum": 50,
            "minimum": 1,
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "null",
              "integer",
              "string"
            ],
            "format": "int32"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "name": "X-Api-Key",
        "in": "header"
      }
    }
  },
  "security": [
    {
      "ApiKey": [ ]
    }
  ],
  "tags": [
    {
      "name": "v1"
    }
  ]
}