swagger: "2.0"
schemes:
  - http
host: core.ac.uk
basePath: /api-v2
info:
  contact:
    x-twitter: oacore
  description: |-
    <p style="text-align: justify;">You can use the CORE API to access the 
        resources harvested and enriched by CORE. If you encounter any problems with the API, please <a href="/contact">report them to us</a>.</p>

    <h2>Overview</h2>
    <p style="text-align: justify;">The API is organised by resource type. The resources are <b>articles</b>, 
        <b>journals</b> and <b>repositories</b> and are represented using JSON data format. Furthermore, 
        each resource has a list of methods. The API also provides two global methods for accessing all resources at once.</p>

    <h2>Response format</h2>
    <p style="text-align: justify;">Response for each query contains two fields: <b>status</b> and <b>data</b>.
        In case of an error status, the data field is empty. The data field contains a single object
        in case the request is for a specific identifier (e.g. CORE ID, CORE repository ID, etc.), or  
        contains a list of objects, for example for search queries. In case of batch requests, the response
        is an array of objects, each of which contains its own <b>status</b> and <b>data</b> fields.
        For search queries the response contains an additional field <b>totalHits</b>, which is the 
        total number of items which match the search criteria.</p>

    <h2>Search query syntax</h2>

    <p style="text-align: justify">Complex search queries can be used in all of the API search methods.
        The query can be a simple string or it can be built using terms and operators described in Elasticsearch
        <a href="http://www.elastic.co/guide/en/elasticsearch/reference/1.4/query-dsl-query-string-query.html#query-string-syntax">documentation</a>.
        The usable field names are <strong>title</strong>, <strong>description</strong>, <strong>fullText</strong>, 
        <strong>authors</strong>, <strong>publisher</strong>, <strong>repositories.id</strong>, <strong>repositories.name</strong>, 
        <strong>doi</strong>, <strong>oai</strong>, <strong>identifiers</strong> (which is a list of article identifiers including OAI, URL, etc.), <strong>language.name</strong> 
        and <strong>year</strong>. Some example queries:
    </p>

    <ul style="margin-left: 30px;">
        <li><p>title:psychology and language.name:English</p></li>
        <li><p>repositories.id:86 AND year:2014</p></li>
        <li><p>identifiers:"oai:aura.abdn.ac.uk:2164/3837" OR identifiers:"oai:aura.abdn.ac.uk:2164/3843"</p></li>
        <li><p>doi:"10.1186/1471-2458-6-309"</p></li>
    </ul>

    <h3>Retrieving the latest Articles</h3>
    <p style="text-align: justify">
        You can retrieve the harvested items since specific dates using the following queries:
    </p>

    <ul style="margin-left: 30px;">
        <li><p>repositoryDocument.metadataUpdated:>2017-02-10</p></li>
        <li><p>repositoryDocument.metadataUpdated:>2017-03-01 AND repositoryDocument.metadataUpdated:<2017-03-31</p></li>    
    </ul>

    <h2>Sort order</h2>

    <p style="text-align: justify;">For search queries, the results are ordered by relevance score. For batch 
        requests, the results are retrieved in the order of the requests.</p>

    <h2>Parameters</h2>
    <p style="text-align: justify;">The API methods allow different parameters to be passed. Additionally, there is an API key parameter which is common to all API methods. For all API methods 
        the API key can be provided either as a query parameter or in the request header. If the API key 
        is not provided, the API will return HTTP 401 error. You can register for an API key <a href="/services#api">here</a>.</p>

    <h2>API methods</h2>
  title: CORE API v2
  version: "2.0"
  x-apisguru-categories:
    - open_data
  x-logo:
    url: https://twitter.com/oacore/profile_image?size=original
  x-origin:
    - converter:
        url: https://github.com/lucybot/api-spec-converter
        version: 2.7.31
      format: swagger
      url: http://core.ac.uk/api-v2/doc
      version: "1.2"
  x-providerName: core.ac.uk
securityDefinitions:
  apiKey:
    description: Your Api Key. Also accepts apiKey as a header
    in: query
    name: apiKey
    type: apiKey
security:
  - apiKey: []
tags:
  - description: Global operations
    name: all
  - description: Operations for retrieving articles
    name: articles
  - description: Operations for retrieving journals
    name: journals
  - description: Operations for retrieving repositories
    name: repositories
paths:
  /articles/dedup:
    post:
      description: Method accepts values for several parameters and retrieves a JSON array of articles which have near duplicate content matching the input parameters' values. The response array contains ids of the near duplicate articles along with their relevance scores.
      operationId: nearDuplicateArticles
      parameters:
        - description: The DOI for which the duplicates will be identified
          in: query
          name: doi
          required: false
          type: string
        - description: Title to match when looking for duplicate articles. Only useful when either value for @year or @description is supplied.
          in: query
          name: title
          required: false
          type: string
        - description: "Year the article was published. Only useful when value for @title is supplied. "
          in: query
          name: year
          required: false
          type: string
        - description: Abstract for an article based on which its duplicates will be found. Only useful when value for @title is supplied.
          in: query
          name: description
          required: false
          type: string
        - description: Full text for an article based on which its duplicates will be found.
          in: query
          name: fulltext
          required: false
          type: string
        - description: Article identifier for which the duplicates will be identified. Only useful when either values for @doi or (@title and @year) or (@title and @abstract) or @fulltext are supplied.
          in: query
          name: identifier
          required: false
          type: string
        - description: "Limit the duplicates search to particular repository id. "
          in: query
          name: repositoryId
          required: false
          type: string
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            $ref: "#/definitions/ArticleDedupResponse"
        "400":
          description: Insufficient/Unsuitable input parameters.
        "401":
          description: Invalid or no API key provided
        "503":
          description: Could not run the deduplication service at this time; please try again later.
      summary: Get all near duplicate articles
      tags:
        - articles
  /articles/get:
    post:
      description: Method accepts a JSON array of CORE IDs and retrieves a list of articles. The response array is ordered based on the order of the IDs in the request array.
      operationId: getArticleByCoreIdBatch
      parameters:
        - description: JSON array with CORE IDs of articles that need to be fetched
          in: body
          name: body
          required: true
          schema:
            items:
              type: integer
            type: array
        - default: true
          description: Whether to retrieve the full article metadata or only the IDs. The default value is true
          in: query
          name: metadata
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve fulltexts of the articles. The default value is false
          in: query
          name: fulltext
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve citations found in the articles. The default value is false
          in: query
          name: citations
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve lists of similar articles. The default value is false. Because the similar articles are calculated on demand, setting this parameter to true might slightly slow down the response time
          in: query
          name: similar
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve CORE IDs of different versions of the articles. The default value is false
          in: query
          name: duplicate
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve lists of URLs of the article fulltexts. The default value is false
          in: query
          name: urls
          required: false
          type: boolean
        - default: false
          description: Returns the records raw XML metadata from the original repository. The default value is false
          in: query
          name: faithfulMetadata
          required: false
          type: boolean
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            items:
              $ref: "#/definitions/ArticleResponse"
            type: array
        "400":
          description: Missing or malformed JSON in request body
        "401":
          description: Invalid or no API key provided
        "403":
          description: Too many queries in request body
        "429":
          description: Too many requests in given amount of time
      summary: Batch operation for retrieving articles by CORE ID
      tags:
        - articles
  "/articles/get/{coreId}":
    get:
      description: Method will retrieve an article based on given CORE ID.
      operationId: getArticleByCoreId
      parameters:
        - description: CORE ID of the article that needs to be fetched.
          format: int64
          in: path
          name: coreId
          required: true
          type: integer
        - default: true
          description: Whether to retrieve the full article metadata or only the ID. The default value is true.
          in: query
          name: metadata
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve full text of the article. The default value is false
          in: query
          name: fulltext
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve citations found in the article. The default value is false
          in: query
          name: citations
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve a list of similar articles. The default value is false. Because the similar articles are calculated on demand, setting this parameter to true might slightly slow down the response time
          in: query
          name: similar
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve a list of CORE IDs of different versions of the article. The default value is false
          in: query
          name: duplicate
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve a list of URLs from which the article can be downloaded. This can include links to PDFs as well as HTML pages. The default value is false
          in: query
          name: urls
          required: false
          type: boolean
        - default: false
          description: Returns the records raw XML metadata from the original repository. The default value is false
          in: query
          name: faithfulMetadata
          required: false
          type: boolean
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            $ref: "#/definitions/ArticleResponse"
        "400":
          description: Invalid identifier supplied
        "401":
          description: Invalid or no API key provided
        "429":
          description: Too many requests in given amount of time
      summary: Get article by CORE ID
      tags:
        - articles
  "/articles/get/{coreId}/download/pdf":
    get:
      description: Method will retrieve an article based on given CORE ID.
      operationId: getArticlePdfByCoreId
      parameters:
        - description: ID of article history that needs to be fetched
          in: path
          name: coreId
          required: true
          type: string
      produces:
        - application/pdf
      responses:
        "200":
          description: Successful operation
        "401":
          description: Invalid or no API key provided
        "404":
          description: No Article pdf found
        "429":
          description: Too many requests in given amount of time
      summary: Get fulltext PDF by CORE ID
      tags:
        - articles
  "/articles/get/{coreId}/history":
    get:
      description: Method accepts a single CORE ID and returns a list of all historical versions of the article, which are stored in CORE database. The results are ordered from the newest one to the oldest one.
      operationId: getArticleHistoryByCoreId
      parameters:
        - description: CORE ID of the article which history should be fetched
          in: path
          name: coreId
          required: true
          type: string
        - default: 1
          description: Which page of the history results should be retrieved. Can be any number betwen 1 and 100, default is 1 (first page).
          format: int32
          in: query
          maximum: 100
          minimum: 1
          name: page
          required: false
          type: integer
        - default: 10
          description: The number of results to return per page. Can be any number between 10 and 100, default is 10.
          format: int32
          in: query
          maximum: 100
          minimum: 10
          name: pageSize
          required: false
          type: integer
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            $ref: "#/definitions/ArticleHistoryResponse"
        "400":
          description: Parameter invalid or out of bounds
        "401":
          description: Invalid or no API key provided
        "429":
          description: Too many requests in given amount of time
      summary: Get article history by CORE ID
      tags:
        - articles
  /articles/search:
    post:
      description: Method accepts a JSON array of search queries and parameters. It then searches through all articles and returns a JSON array of search results for each of the queries. Method searches through all article fields (title, authors, subjects, identifiers, etc.).
      operationId: searchArticlesBatch
      parameters:
        - description: JSON array with search queries and parameters. One request can contain up to 100 queries
          in: body
          name: body
          required: true
          schema:
            items:
              $ref: "#/definitions/SearchRequest"
            type: array
        - default: true
          description: Whether to retrieve the full article metadata or only the ID. The default value is true.
          in: query
          name: metadata
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve full text of the article. The default value is false
          in: query
          name: fulltext
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve citations found in the article. The default value is false
          in: query
          name: citations
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve a list of similar articles. The default value is false. Because the similar articles are calculated on demand, setting this parameter to true might slightly slow down the response time
          in: query
          name: similar
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve a list of CORE IDs of different versions of the article. The default value is false
          in: query
          name: duplicate
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve a list of URLs from which the article can be downloaded. This can include links to PDFs as well as HTML pages. The default value is false
          in: query
          name: urls
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve the raw XML metadata of the article. The default value is false
          in: query
          name: faithfulMetadata
          required: false
          type: boolean
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            items:
              $ref: "#/definitions/ArticleSearchResponse"
            type: array
        "400":
          description: Missing or malformed JSON in request body
        "401":
          description: Invalid or no API key provided
        "403":
          description: Too many queries in request body
        "429":
          description: Too many requests in given amount of time
      summary: Batch operation for search through articles
      tags:
        - articles
  "/articles/search/{query}":
    get:
      description: Searches through all articles and returns a JSON array with search results. Method searches through all article fields.
      operationId: searchArticles
      parameters:
        - description: The search query
          format: int64
          in: path
          name: query
          required: true
          type: integer
        - default: 1
          description: Which page of the search results should be retrieved. Can be any number betwen 1 and 100, default is 1 (first page).
          format: int32
          in: query
          maximum: 100
          minimum: 1
          name: page
          required: false
          type: integer
        - default: 10
          description: The number of results to return per page. Can be any number between 10 and 100, default is 10.
          format: int32
          in: query
          maximum: 100
          minimum: 10
          name: pageSize
          required: false
          type: integer
        - default: true
          description: Whether to retrieve the full article metadata or only the ID. The default value is true.
          in: query
          name: metadata
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve full text of the article. The default value is false
          in: query
          name: fulltext
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve citations found in the article. The default value is false
          in: query
          name: citations
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve a list of similar articles. The default value is false. Because the similar articles are calculated on demand, setting this parameter to true might slightly slow down the response time
          in: query
          name: similar
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve a list of CORE IDs of different versions of the article. The default value is false
          in: query
          name: duplicate
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve a list of URLs from which the article can be downloaded. This can include links to PDFs as well as HTML pages. The default value is false
          in: query
          name: urls
          required: false
          type: boolean
        - default: false
          description: Returns the records raw XML metadata from the original repository. The default value is false
          in: query
          name: faithfulMetadata
          required: false
          type: boolean
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            $ref: "#/definitions/ArticleSearchResponse"
        "400":
          description: Parameter invalid or out of bounds
        "401":
          description: Invalid or no API key provided
        "429":
          description: Too many requests in given amount of time
      summary: Search through all documents
      tags:
        - articles
  /articles/similar:
    post:
      description: Method accepts a text and retrieves a JSON array of articles which are similar to the given text. The response array is ordered based on similarity score, starting from the most similar.
      operationId: similarArticles
      parameters:
        - description: The text that requires similar articles to be calculated on
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/SimilarRequest"
        - default: 10
          description: How many similar articles to retrieve at most. Can be any number betwen 1 and 100, default is 10
          in: query
          maximum: 100
          minimum: 1
          name: limit
          required: false
          type: integer
        - default: true
          description: Whether to retrieve the full article metadata or only the IDs of the similar articles. The default value is true
          in: query
          name: metadata
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve fulltexts of the similar articles. The default value is false
          in: query
          name: fulltext
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve citations found in the articles. The default value is false
          in: query
          name: citations
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve lists of similar articles. The default value is false. Because the similar articles are calculated on demand, setting this parameter to true might slightly slow down the response time
          in: query
          name: similar
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve CORE IDs of different versions of the articles. The default value is false
          in: query
          name: duplicate
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve lists of URLs of the article fulltexts. The default value is false
          in: query
          name: urls
          required: false
          type: boolean
        - default: false
          description: Whether to retrieve the raw XML metadata of the articles. The default value is false
          in: query
          name: faithfulMetadata
          required: false
          type: boolean
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            $ref: "#/definitions/ArticleSimilarResponse"
        "400":
          description: Missing text in request body or parameter out of bounds or invalid parameter
        "401":
          description: Invalid or no API key provided
        "429":
          description: Too many requests in given amount of time
      summary: Get articles by similarity to a text
      tags:
        - articles
  /journals/get:
    post:
      description: Method accepts a JSON array of ISSNs and retrieves a list of journals.
      operationId: getJournalByIssnBatch
      parameters:
        - description: JSON array with ISSNs of journals that need to be fetched
          in: body
          name: body
          required: true
          schema:
            items:
              type: string
            type: array
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            items:
              $ref: "#/definitions/JournalResponse"
            type: array
        "400":
          description: Missing or malformed JSON in request body
        "401":
          description: Invalid or no API key provided
        "403":
          description: Too many queries in request body
      summary: Batch operation for retrieving journals by ISSN
      tags:
        - journals
  "/journals/get/{issn}":
    get:
      description: Returns a journal with given ISSN identifier.
      operationId: getJournalByIssn
      parameters:
        - description: ISSN identifier of journal that needs to be fetched.
          in: path
          name: issn
          required: true
          type: string
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            $ref: "#/definitions/JournalResponse"
        "400":
          description: Invalid ISSN identifier supplied
        "401":
          description: Invalid or no API key provided
      summary: Find journal by ISSN
      tags:
        - journals
  /journals/search:
    post:
      description: Method accepts a JSON array of search queries and parameters. It then searches through all journals and returns a JSON array of search results for each of the queries. Method searches through all journal fields (title, identifiers, subjects, language, rights and publisher).
      parameters:
        - description: JSON array with search queries and parameters. One request can contain up to 100 queries.
          in: body
          name: body
          required: true
          schema:
            items:
              $ref: "#/definitions/SearchRequest"
            type: array
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            items:
              $ref: "#/definitions/JournalResponse"
            type: array
        "400":
          description: Missing or malformed JSON in request body
        "401":
          description: Invalid or no API key provided
        "403":
          description: Too many queries in request body
      summary: Batch operation for search through journals
      tags:
        - journals
  "/journals/search/{query}":
    get:
      description: Searches through all journals and returns a JSON array of search results. Method searches through all journal fields (title, identifiers, subjects, language, rights and publisher).
      parameters:
        - description: Search query
          in: path
          name: query
          required: true
          type: string
        - default: 1
          description: Which page of the search results should be retrieved. Can be any number betwen 1 and 100, default is 1 (first page).
          format: int32
          in: query
          maximum: 100
          minimum: 1
          name: page
          required: false
          type: integer
        - default: 10
          description: The number of results to return per page. Can be any number between 10 and 100, default is 10.
          format: int32
          in: query
          maximum: 100
          minimum: 10
          name: pageSize
          required: false
          type: integer
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            $ref: "#/definitions/JournalSearchResponse"
        "400":
          description: Parameter invalid or out of bounds
        "401":
          description: Invalid or no API key provided
      summary: Search through journals
      tags:
        - journals
  /repositories/get:
    post:
      description: Method accepts a JSON array of CORE repository IDs and retrieves a list of repositories. The response array is ordered based on the order of the IDs in the request array. The maximum number of IDs in request is 100.
      operationId: getRepositoryByIdBatch
      parameters:
        - description: JSON array with CORE repository IDs of repositories that need to be fetched
          in: body
          name: body
          required: true
          schema:
            items:
              type: integer
            type: array
        - default: false
          description: Whether to retrieve statistics about the repository. The default value is false
          in: query
          name: stats
          required: false
          type: boolean
        - default: false
          description: Returns deposit history over time
          in: query
          name: depositHistory
          required: false
          type: boolean
        - default: false
          description: Returns deposit history over time
          in: query
          name: depositHistoryCumulative
          required: false
          type: boolean
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            items:
              $ref: "#/definitions/RepositoryResponse"
            type: array
        "400":
          description: Missing or malformed JSON in request body
        "401":
          description: Invalid or no API key provided
        "403":
          description: Too many queries in request body
        "429":
          description: Too many requests in given amount of time
      summary: Batch operation for retrieving repositories by CORE repository ID
      tags:
        - repositories
  "/repositories/get/{repositoryId}":
    get:
      description: Method will retrieve a repository based on given CORE repository ID.
      operationId: getRepositoryById
      parameters:
        - description: CORE repository ID of the article that needs to be fetched.
          in: path
          name: repositoryId
          required: true
          type: integer
        - default: false
          description: Whether to retrieve statistics about the repository. The default value is false
          in: query
          name: stats
          required: false
          type: boolean
        - default: false
          description: Returns deposit history over time
          in: query
          name: depositHistory
          required: false
          type: boolean
        - default: false
          description: Returns deposit history over time
          in: query
          name: depositHistoryCumulative
          required: false
          type: boolean
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            $ref: "#/definitions/RepositoryResponse"
        "400":
          description: Invalid identifier supplied
        "401":
          description: Invalid or no API key provided
        "429":
          description: Too many requests in given amount of time
      summary: Get repository by CORE repository ID
      tags:
        - repositories
  /repositories/search:
    post:
      description: Method accepts a JSON array of search queries and parameters. It then searches through all repositories and returns a JSON array of search results for each of the queries. Method searches through all repository fields.
      parameters:
        - description: JSON array with search queries and parameters. One request can contain up to 100 queries
          in: body
          name: body
          required: true
          schema:
            items:
              $ref: "#/definitions/SearchRequest"
            type: array
        - default: false
          description: Whether to retrieve statistics about the repository. The default value is false
          in: query
          name: stats
          required: false
          type: boolean
        - default: false
          description: Returns deposit history over time
          in: query
          name: depositHistory
          required: false
          type: boolean
        - default: false
          description: Returns deposit history over time
          in: query
          name: depositHistoryCumulative
          required: false
          type: boolean
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            $ref: "#/definitions/RepositorySearchResponse"
        "400":
          description: Missing or malformed JSON in request body
        "401":
          description: Invalid or no API key provided
        "403":
          description: Too many queries in request body
        "429":
          description: Too many requests in given amount of time
      summary: Batch operation for searching through repositories
      tags:
        - repositories
  "/repositories/search/{query}":
    get:
      description: Searches through all repositories and returns a JSON array with search results. Method searches through all repository fields.
      parameters:
        - description: The search query
          in: path
          name: query
          required: true
          type: string
        - default: 1
          description: Which page of the search results should be retrieved. Can be any number betwen 1 and 100, default is 1 (first page).
          format: int32
          in: query
          maximum: 100
          minimum: 1
          name: page
          required: false
          type: integer
        - default: 10
          description: The number of results to return per page. Can be any number between 10 and 100, default is 10.
          format: int32
          in: query
          maximum: 100
          minimum: 10
          name: pageSize
          required: false
          type: integer
        - default: false
          description: Whether to retrieve statistics about the repository. The default value is false
          in: query
          name: stats
          required: false
          type: boolean
        - default: false
          description: Returns deposit history over time
          in: query
          name: depositHistory
          required: false
          type: boolean
        - default: false
          description: Returns deposit history over time
          in: query
          name: depositHistoryCumulative
          required: false
          type: boolean
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            $ref: "#/definitions/RepositorySearchResponse"
        "400":
          description: Parameter invalid or out of bounds
        "401":
          description: Invalid or no API key provided
        "429":
          description: Too many requests in given amount of time
      summary: Search through all repositories
      tags:
        - repositories
  /search:
    post:
      description: Method accepts a JSON array of search queries. It searches through all resources and returns a JSON array with search results for each of the queries. Method searches through all resources and all fields. The results are ordered by relevance score and contain type of the relevant resource and its ID. Furthermore, the responses are oredered based on the order of the request items. The metadata of each resource need to be obtained through an appropriate method.
      parameters:
        - description: JSON array with search queries and pagination parameters. One request can contain up to 100 queries
          in: body
          name: body
          required: true
          schema:
            items:
              $ref: "#/definitions/SearchRequest"
            type: array
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            items:
              $ref: "#/definitions/SearchAllResponse"
            type: array
        "400":
          description: Missing or malformed JSON in request body
        "401":
          description: Invalid or no API key provided
        "403":
          description: Too many queries in request body
        "429":
          description: Too many requests in given amount of time
      summary: Batch operation for search through all resources
      tags:
        - all
  "/search/{query}":
    get:
      description: Searches through all resources and returns a JSON array with search results. Method searches through all resources and all fields. The results are ordered by relevance score and contain type of the relevant resource and its ID. The metadata of each resource need to be obtained through an appropriate method.
      parameters:
        - description: The search query
          in: path
          name: query
          required: true
          type: string
        - default: 1
          description: Which page of the search results should be retrieved. Can be any number betwen 1 and 100, default is 1 (first page).
          format: int32
          in: query
          maximum: 100
          minimum: 1
          name: page
          required: false
          type: integer
        - default: 10
          description: The number of results to return per page. Can be any number between 10 and 100, default is 10.
          format: int32
          in: query
          maximum: 100
          minimum: 10
          name: pageSize
          required: false
          type: integer
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            $ref: "#/definitions/SearchAllResponse"
        "400":
          description: Parameter invalid or out of bounds
        "401":
          description: Invalid or no API key provided
        "429":
          description: Too many requests in given amount of time
      summary: Search through all resources
      tags:
        - all
definitions:
  Article:
    properties:
      authors:
        description: List of article authors
        items:
          type: string
        type: array
      citations:
        description: Citations found in the article
        items:
          $ref: "#/definitions/Citation"
        type: array
      contributors:
        description: List of article contributors
        items:
          type: string
        type: array
      datePublished:
        description: Date article published
        type: string
      description:
        description: The abstract
        type: string
      doi:
        description: The DOI of the article
        type: string
      downloadUrl:
        description: The download PDF URL which is displayed on our /display/[ArticleID] page
        type: string
      fulltext:
        description: Article full text
        type: string
      fulltextIdentifier:
        description: The URL to the fulltext
        type: string
      fulltextUrls:
        description: URLs of the fulltext version of this article
        items:
          type: string
        type: array
      id:
        description: Article ID
        type: integer
      identifiers:
        description: List of document identifiers
        items:
          type: string
        type: array
      journals:
        description: List of journals this article belongs to
        items:
          $ref: "#/definitions/ArticleJournal"
        type: array
      language:
        $ref: "#/definitions/Language"
        description: Language of the article
      oai:
        description: The OAI of the article
        type: string
      publisher:
        description: Publisher of the article
        type: string
      rawRecordXml:
        $ref: "#/definitions/RawRecordXml"
        description: Raw XML metadata
      relations:
        description: URLs of relating articles, etc.
        items:
          type: string
        type: array
      repositories:
        description: List of repositories this article belongs to
        items:
          $ref: "#/definitions/Repository"
        type: array
      repositoryDocument:
        $ref: "#/definitions/RepositoryDocument"
        description: Information of CORE harvesting
      similarities:
        description: Similar articles
        items:
          $ref: "#/definitions/Similar"
        type: array
      subjects:
        description: Article subjects
        items:
          type: string
        type: array
      title:
        description: Article title
        type: string
      topics:
        description: Article topics
        items:
          type: string
        type: array
      types:
        description: Types, e.g. conference paper, journal paper, etc.
        items:
          type: string
        type: array
      year:
        description: Year the article was published
        type: integer
    required:
      - id
  ArticleDedupResponse: {}
  ArticleHistoryResponse:
    properties:
      data:
        description: List of article versions
        items:
          $ref: "#/definitions/RawRecordXml"
        type: array
      status:
        description: Operation status
        enum:
          - OK
          - Not found
          - Too many queries
          - Missing parameter
          - Invalid parameter
          - Parameter out of bounds
        type: string
    required:
      - status
  ArticleJournal:
    properties:
      identifiers:
        description: List of journal identifiers
        items:
          type: string
        type: array
      title:
        description: Title of the journal
        type: string
  ArticleResponse:
    properties:
      data:
        $ref: "#/definitions/Article"
        description: The fetched article
      status:
        description: Operation status
        enum:
          - OK
          - Not found
          - Too many queries
          - Missing parameter
          - Invalid parameter
          - Parameter out of bounds
        type: string
    required:
      - data
      - status
  ArticleSearchResponse:
    properties:
      data:
        description: Search results
        items:
          $ref: "#/definitions/Article"
        type: array
      status:
        description: Operation status
        enum:
          - OK
          - Not found
          - Too many queries
          - Missing parameter
          - Invalid parameter
          - Parameter out of bounds
        type: string
      totalHits:
        description: Total number of articles matching the search criteria
        type: integer
    required:
      - data
      - status
      - totalHits
  ArticleSimilarResponse:
    properties:
      data:
        description: Similar articles
        items:
          $ref: "#/definitions/Article"
        type: array
      status:
        description: Operation status
        enum:
          - OK
          - Not found
          - Too many queries
          - Missing parameter
          - Invalid parameter
          - Parameter out of bounds
        type: string
    required:
      - data
      - status
  Citation:
    properties:
      authors:
        description: Authors of the article
        type: string
      date:
        description: Date the cited article was published
        type: string
      doi:
        description: Digital Object Identifier
        type: string
      raw:
        description: Citation as raw string
        type: string
      title:
        description: Title of the cited article
        type: string
  Journal:
    properties:
      identifiers:
        description: List of journal identifiers (e.g. URL, OAI or ISSN). The type is prepended to the identifier string (e.g. 'issn:2296-0597')
        items:
          type: string
        type: array
      language:
        description: Language of the journal
        type: string
      publisher:
        description: Publisher of the journal
        type: string
      rights:
        description: Copyright license of the journal
        type: string
      subjects:
        description: List of journal subjects
        items:
          type: string
        type: array
      title:
        description: Journal title
        type: string
    required:
      - identifiers
  JournalResponse:
    properties:
      data:
        $ref: "#/definitions/Journal"
        description: The fetched journal
      status:
        description: Operation status
        enum:
          - OK
          - NOT_FOUND
          - TOO_MANY_QUERIES
          - MISSING_PARAMETER
          - INVALID_PARAMETER
        type: string
    required:
      - status
  JournalSearchResponse:
    properties:
      data:
        description: Search results
        items:
          $ref: "#/definitions/Journal"
        type: array
      status:
        description: Operation status
        enum:
          - OK
          - NOT_FOUND
          - TOO_MANY_QUERIES
          - MISSING_PARAMETER
          - INVALID_PARAMETER
        type: string
      totalHits:
        description: Total number of journals matching the search criteria
        type: integer
    required:
      - status
      - totalHits
  Language:
    properties:
      deletedStatus:
        description: "The deleted status of the document: 0 for allowed, 1 for deleted, 2 for disabled"
        type: integer
      depositedDate:
        description: The date the item was deposited in the Data Provider (repository/Journal)
        format: date
        type: string
      indexed:
        description: "The index status of the document: 0 for not indexed, 1 for indexed"
        type: integer
      metadataUpdated:
        description: The last date metadata of this article were updated
        format: date
        type: string
      pdfOrigin:
        description: The remote URL where we aquired the PDF
        type: string
      pdfSize:
        description: The size of pdf in bytes
        type: integer
      pdfStatus:
        description: "The pdf status flag of article: 0 no pdf, 1 pdf exists"
        type: integer
      tdmOnly:
        description: "The tdmOnly flag of the article: 0 normal, 1 tdm only"
        type: boolean
      textStatus:
        description: "The text status flag of article: 0 does not exist, 1 exists"
        type: integer
      timestamp:
        description: The date of article as given by the repository
        format: date
        type: string
  RawRecordXml:
    properties:
      datetime:
        description: Timestamp when CORE harvested the metadata
        format: date-format
        type: string
      metadata:
        description: The raw XML metadata
        type: string
  Repository:
    properties:
      dataProviderSourceStats:
        description: Statistics based on the Data Provider/repository rather than data processed and filtered by CORE. This array is in beta and may change in the future
        items: {}
        type: array
      history:
        description: The number of deposits in the repository per date. This field is in beta and may change in the future
        items: {}
        type: array
      historyCumulative:
        description: The number of deposits in the repository per date over time (cumulative). This field is in beta and may change in the future
        items: {}
        type: array
      id:
        description: CORE repository ID
        type: integer
      lastSeen:
        description: The time the repository was last harvested by CORE. This field is in beta and may change in the future
        format: date-time
        type: string
      name:
        description: Repository name
        type: string
      openDoarId:
        description: ID of the repository in Open DOAR
        type: integer
      repositoryLocation:
        $ref: "#/definitions/RepositoryLocation"
        description: Location of the repository
      repositoryStats:
        $ref: "#/definitions/RepositoryStats"
        description: Statistics about the repository
      uri:
        description: Repository URI
        type: string
      urlHomepage:
        description: Repository homepage
        type: string
      urlOaipmh:
        description: Repository OAI-PMH endpoint
        type: string
  RepositoryDocument: {}
  RepositoryLocation:
    properties:
      country:
        description: Country name
        type: string
      countryCode:
        description: Two letter country code
        type: string
      id:
        description: CORE repository ID
        type: integer
      latitude:
        type: integer
      longitude:
        type: integer
      repositoryName:
        description: Repository name
        type: string
  RepositoryResponse:
    properties:
      data:
        $ref: "#/definitions/Repository"
        description: The fetched repository
      status:
        description: Operation status
        enum:
          - OK
          - Not found
          - Too many queries
          - Missing parameter
          - Invalid parameter
          - Parameter out of bounds
        type: string
    required:
      - status
  RepositorySearchResponse:
    properties:
      data:
        description: Search results
        items:
          $ref: "#/definitions/Repository"
        type: array
      status:
        description: Operation status
        enum:
          - OK
          - Not found
          - Too many queries
          - Missing parameter
          - Invalid parameter
          - Parameter out of bounds
        type: string
      totalHits:
        description: Total number of repositories matching the search criteria
        type: integer
    required:
      - status
      - totalHits
  RepositoryStats:
    properties:
      countFulltext:
        description: Repository fulltext count
        type: integer
      countMetadata:
        description: Repository metadata count
        type: integer
      dateLastProcessed:
        description: Last repository processing date
        type: string
  Resource:
    properties:
      id:
        description: Identifier of the resource
        type: string
      type:
        description: Type of the resource
        enum:
          - journal
          - article
          - repository
        type: string
    required:
      - id
      - type
  SearchAllResponse:
    properties:
      data:
        description: List of relevant resources
        items:
          $ref: "#/definitions/Resource"
        type: array
      status:
        description: Operation status
        enum:
          - OK
          - Not found
          - Too many queries
          - Missing parameter
          - Invalid parameter
          - Parameter out of bounds
        type: string
      totalHits:
        description: Total number of items matching the search criteria
        type: integer
    required:
      - data
      - status
      - totalHits
  SearchRequest:
    properties:
      page:
        default: 1
        description: Which page of the search results should be retrieved. Can be any number from 1 to 100, default is 1 (first page)
        maximum: 100
        minimum: 1
        type: integer
      pageSize:
        default: 10
        description: The number of results to return per page. Can be any number from 10 to 100, default is 10
        maximum: 100
        minimum: 10
        type: integer
      query:
        description: Search query
        type: string
    required:
      - query
  Similar:
    properties:
      id:
        description: CORE ID of the similar article
        type: integer
      score:
        description: Similarity score
        format: double
        type: number
      title:
        description: Title of the similar article
        type: string
    required:
      - id
      - score
  SimilarRequest:
    properties:
      text:
        description: Find Similar articles based on this string
        type: string
    required:
      - text
