ScholarSphere API

openapi: 3.0.2
x-generated: '2026-08-30'
x-method: searched
x-source-url: https://raw.githubusercontent.com/psu-libraries/scholarsphere/main/openapi.yml
x-operator: institution
x-provenance: 'Penn State University Libraries wrote and publishes this OpenAPI in its own ScholarSphere
  repository under MIT; fetched verbatim 2026-08-30 (200, 20,960 bytes) and archived byte-identical at
  openapi/_original/pennsylvania-state-university-scholarsphere.yaml. The only edit to this copy is a
  clarified info.title and info.contact; the servers[] block (https://scholarsphere.psu.edu/api/{version})
  is the provider''s own and was confirmed live by probe (GET /api/v1/dois -> 401 application/json). No
  path, parameter, schema or response was altered. A code host is not a vendor: this contract describes
  a service Penn State operates on a psu.edu host. Penn State''s published document leaves every operation
  UNTAGGED; refine-openapis requires a tag on each. Tags were added to THIS copy only, named directly
  after the paths the provider already defined (/ingest, /collections, /dois, /files, /featured_resources,
  /uploads). No operation, parameter, schema or response was changed, and openapi/_original/ keeps the
  untagged original.'
info:
  title: ScholarSphere API
  description: API specification for ScholarSphere
  termsOfService: https://scholarsphere.psu.edu/about
  contact:
    name: ScholarSphere Support (Penn State University Libraries)
    url: https://docs.scholarsphere.psu.edu/
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: '1.0'
servers:
- url: https://scholarsphere.psu.edu/api/{version}
  description: API endpoint
  variables:
    version:
      description: Version of the API
      enum:
      - v1
      default: v1
tags:
- name: Ingest
  description: Deposit a new work into ScholarSphere with its metadata, files and permissions.
- name: Collections
  description: Create collections that group deposited works.
- name: DOIs
  description: The public index of DataCite DOIs ScholarSphere knows about (Penn State prefix 10.26207).
- name: Files
  description: Attach or replace files on an existing work.
- name: Featured Resources
  description: Promote a resource on the ScholarSphere home page.
- name: Uploads
  description: Request a presigned destination for a direct file upload.
paths:
  /ingest:
    post:
      summary: Publishes a new work
      description: Creates a new work with a single version, and if all the requirements are present,
        the version will be published and publicly available.
      security:
      - APIKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ingest'
      responses:
        200:
          description: The work was successfully published
        201:
          description: The work was created, but not published
        default:
          $ref: '#/components/responses/defaultPostError'
      tags:
      - Ingest
  /collections:
    post:
      summary: Creates a new collection
      tags:
      - Collections
  /dois:
    get:
      summary: List of all DOIs
      description: Retrieve a dictionary of all DOIs known to Scholarsphere. The keys in this dictionary
        will be the DOI, like `"doi:10.26207/002c-bb83"` and the value will be an array of UUIDs of all
        resources that reference that DOI
      security:
      - APIKey: []
      responses:
        200:
          description: A list of all DOIs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/doi_list'
      tags:
      - DOIs
  /dois/{doi}:
    get:
      summary: Search for a DOI
      description: Retrieve a list of resources that mention the given DOI.
      security:
      - APIKey: []
      parameters:
      - name: doi
        in: path
        description: A DOI name, including the slash ("/"). Just put the slash right in the url, like
          `/dois/10.26207/002c-bb83`
        required: true
        schema:
          type: string
          example: 10.26207/002c-bb83
      responses:
        200:
          description: The DOI was found in one or more resources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/doi_response'
        404:
          description: The DOI was not found in any of ScholarSphere's resources
      tags:
      - DOIs
  /files:
    put:
      summary: Updates a file's metadata
      description: The client can update a file's metadata, such as the results of a virus scan or other
        async process.
      security:
      - APIKey: []
      requestBody:
        description: Posting updating information for a file after checking for viruses
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/fileMetadata'
            examples:
              novirus:
                summary: No virus was found in the file
                description: Client posts a json object containing the results of the virus check and
                  when it was performed.
                value:
                  id: '1'
                  metadata:
                    virus:
                      status: 'false'
                      scanned_at: '2021-01-25'
              yesvirus:
                summary: A virus was found in the file
                description: Client posts a json object containing a positive virus check and when it
                  was performed.
                value:
                  id: '1'
                  metadata:
                    virus:
                      status: 'true'
                      scanned_at: '2021-01-25'
      responses:
        200:
          description: The file's metadata was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/successResponse'
              examples:
                summary: The client is not authorized to perform the requested action
                value:
                  message: File was successfully updated
        default:
          $ref: '#/components/responses/defaultPostError'
      tags:
      - Files
  /featured_resources:
    post:
      summary: Adds a new featured resource to the home page
      security:
      - APIKey: []
      requestBody:
        description: Given an existing UUID for a resource, feature it on the homepage
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/featuredResource'
            examples:
              standard:
                summary: Makes this work a featured work on the homepage
                description: Client posts a json object containing the uuid of the resource they want
                  to have featured.
                value:
                  uuid: a0fc525b-0d49-48e0-a385-f86bd13bce4d
      responses:
        200:
          description: If the resources has been featured before, or is already featured, it will update
            with a new timestamp and moved to the top of the list.
        201:
          description: The resource has not been featured before, and a new entry is made in the list
            of featured resources, moving this one to the top.
        default:
          $ref: '#/components/responses/defaultPostError'
      tags:
      - Featured Resources
  /uploads:
    post:
      summary: Requests a pre-signed URL to upload a file into ScholarSphere's S3 instance
      security:
      - APIKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/uploads'
      tags:
      - Uploads
components:
  schemas:
    doi_list:
      type: object
      additionalProperties:
        type: array
        description: a list of resource UUIDs
        items:
          type: string
          description: a resource UUID
          example: a0fc525b-0d49-48e0-a385-f86bd13bce4d
      example:
        doi:10.26207/002c-bb83:
        - a0fc525b-0d49-48e0-a385-f86bd13bce4d
        - 146a74e3-ae66-4802-b5f8-471bcac80d58
        doi:10.18113/dmnf-6dzs:
        - 87287b53-76be-424e-b202-bc6d521c841b
    doi_response:
      type: array
      items:
        type: object
        properties:
          url:
            type: string
            format: uri
            example: /resources/a0fc525b-0d49-48e0-a385-f86bd13bce4d
            description: path to a Scholarsphere resource
    uuid:
      type: object
      properties:
        uuid:
          type: string
          example: a0fc525b-0d49-48e0-a385-f86bd13bce4d
    id:
      type: object
      properties:
        id:
          type: integer
          example: '1'
    metadata:
      type: object
      required:
      - title
      - work_type
      - description
      - published_date
      - creators
      - rights
      - visibility
      properties:
        title:
          type: string
          example: Classifying Independent Hybridity
        work_type:
          type: string
          enum:
          - article
          - audio
          - book
          - collection
          - conference_proceeding
          - dataset
          - image
          - instrument
          - journal
          - map_or_cartographic_material
          - masters_culminating_experience
          - other
          - part_of_book
          - poster
          - presentation
          - professional_doctoral_culminating_experience
          - project
          - report
          - research_paper
          - software_or_program_code
          - video
          example: dataset
        description:
          type: string
          example: Anaesthesiology anthropology chaology craniology ecology endocrinology epileptology
            gnomonics ichthyology linguistics mammalogy mazology nasology nematology neurobiology palaeontology
            psychopathology pterylology textology toponymics. Aerostatics anemology avionics diplomatology
            euthenics geochemistry historiography historiology hydrology hydrometeorology hygiastics iatromathematics
            lexigraphy martyrology metallogeny neonatology numismatics oikology patrology pestology photobiology
            psychobiology psychology sphagnology stemmatology threpsology ufology vinology. Arctophily
            astrophysics carcinology dactylology electrology genealogy horography hydrobiology immunopathology
            lexigraphy molinology nidology paidonosology palaeopedology venereology.
        published_date:
          type: string
          format: date
          example: '2020-10-31'
          description: EDTF date formats are also supported. See https://www.loc.gov/standards/datetime/
        publisher_statement:
          type: string
          example: This is a pre-print from Joe Publisher, Inc. We are not responsible for anything.
          description: This is also referred to as a "set statement" and is often a required part for
            Open Access articles.
        keyword:
          type: array
          items:
            type: string
          example:
          - optics
          - quantum physics
          - fake paper names
        subtitle:
          type: string
          example: Quantum Optics and/in the Clan
        publisher:
          type: array
          items:
            type: string
        subject:
          type: array
          items:
            type: string
        language:
          type: array
          items:
            type: string
        identifier:
          type: array
          items:
            type: string
        based_near:
          type: array
          items:
            type: string
        owner:
          type: string
        manufacturer:
          type: string
        model:
          type: string
        instrument_type:
          type: string
        measured_variable:
          type: string
        available_date:
          type: string
        decommission_date:
          type: string
        related_identifier:
          type: string
        instrument_resource_type:
          type: string
        funding_reference:
          type: string
        related_url:
          type: array
          items:
            type: string
        sub_work_type:
          type: string
          enum:
          - Capstone Course Work Product
          - Capstone Project
          - Culminating Research Project
          - Doctor of Nursing Practice Project
          - Integrative Doctoral Research Project
          - Praxis Project
          - Public Performance
          - Scholarly Paper/Essay (MA/MS)
          example: Capstone Project
        program:
          type: string
          example: Acoustics
        degree:
          type: string
          enum:
          - Doctor of Education
          - Doctor of Musical Arts
          - Doctor of Nursing Practice
          - Doctor of Public Health
          - Doctor of Business Administration
          - Doctor of Engineering
          - Master of Arts
          - Master of Science
          example: Master of Science
        source:
          type: array
          items:
            type: string
        creators:
          type: array
          items:
            $ref: '#/components/schemas/creator'
        contributor:
          type: array
          items:
            type: string
          example:
          - Dr. Phyllis Abracadabra
          - Harry L. Snethers
        rights:
          type: string
          enum:
          - https://creativecommons.org/licenses/by/4.0/
          - https://creativecommons.org/licenses/by-sa/4.0/
          - https://creativecommons.org/licenses/by-nc/4.0/
          - https://creativecommons.org/licenses/by-nd/4.0/
          - https://creativecommons.org/licenses/by-nc-nd/4.0/
          - https://creativecommons.org/licenses/by-nc-sa/4.0/
          - http://creativecommons.org/publicdomain/mark/1.0/
          - http://creativecommons.org/publicdomain/zero/1.0/
          - https://rightsstatements.org/page/InC/1.0/
          - http://www.apache.org/licenses/LICENSE-2.0
          - https://www.gnu.org/licenses/gpl.html
          - https://opensource.org/licenses/MIT
          - https://opensource.org/licenses/BSD-3-Clause
          example: https://creativecommons.org/licenses/by/4.0/
        visibility:
          type: string
          enum:
          - open
          - authenticated
        open_access:
          type: boolean
          description: Whether the work is an upload for open access compliance.
        imported_metadata_from_rmd:
          type: boolean
          description: Whether the metadata was imported from The Researcher Metadata Database (RMD).
        embargoed_until:
          type: string
          format: date
        version_name:
          type: string
          example: 1.0.0
          description: Must be in semantic version format. See https://semver.org/
        doi:
          type: string
          example: doi:10.26207/002c-bb83
          description: A DOI minted under Scholarsphere's current prefix, 10.26207. If you have another
            DOI that was previously supplied by a publisher or someone else, that can be put into the
            identifier field.
    creator:
      type: object
      required:
      - display_name
      properties:
        display_name:
          type: string
          example: Dr. Pat Researcher
        surname:
          type: string
          example: Researcher
        given_name:
          type: string
          example: Pat
        email:
          type: string
          example: pat@example.com
        psu_id:
          type: string
          example: axb123
        orcid:
          type: string
          example: 0000-0000-1234-123X
    ingest:
      type: object
      required:
      - metadata
      - depositor
      - content
      properties:
        metadata:
          $ref: '#/components/schemas/metadata'
        content:
          type: array
          description: Files that have been uploaded to S3 in a previous step. The location information
            for each one, as well as their original names and mime types, is included here.
          items:
            $ref: '#/components/schemas/uploadedFile'
        depositor:
          type: string
          example: axc123
          description: The Penn State access of the person who is depositing the work. This is typically
            the same person who is the creator, but not always. There is no restriction regarding who
            the depositor is other than they must have an active account in Penn State's identity management
            system.
        permissions:
          $ref: '#/components/schemas/permissions'
        publish:
          type: boolean
          example: 'false'
          description: Whether the ingest call should publish the Work or simply create a draft. If left
            blank, this will default to "true"
    uploads:
      type: object
      required:
      - extension
      - content_md5
      properties:
        extension:
          type: string
          description: Three-letter file extension of the file your are requesting to upload into S3.
            This is used to created a unique filename for the file in S3.
        content_md5:
          type: string
          description: Binary encoded md5 checksum of the file you are requesting to upload into S3. This
            is required so that we can verify the integrity of the file when it is uploaded into S3.
    uploadedFile:
      type: object
    permissions:
      type: object
      description: Additional permissions for the work such as users or groups that can edit work. By
        default, only the depositor may edit the work after it has been uploaded.
    featuredResource:
      allOf:
      - $ref: '#/components/schemas/uuid'
      - type: object
        required:
        - uuid
    errorResponse:
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        errors:
          type: array
          items:
            type: string
    fileMetadata:
      required:
      - id
      properties:
        id:
          $ref: '#/components/schemas/id'
        metadata:
          allOf:
          - $ref: '#/components/schemas/virusCheck'
    successResponse:
      required:
      - message
      properties:
        message:
          type: string
    virusCheck:
      properties:
        status:
          type: string
          format: boolean
          enum:
          - true
          - false
        scanned_at:
          type: string
          format: date
  securitySchemes:
    APIKey:
      type: apiKey
      description: Key-based authorization mechanism to the API. A key is obtained fron the ScholarSphere
        team and is included in the header of all requests.
      name: X_API_KEY
      in: header
  responses:
    defaultPostError:
      description: If the resource can't be created, then there is some kind of error. The client can
        interpret the responses.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            unauthorized:
              $ref: '#/components/examples/unauthorized'
            notFound:
              $ref: '#/components/examples/notFound'
            unprocessableEntity:
              $ref: '#/components/examples/unprocessableEntity'
            serverError:
              $ref: '#/components/examples/serverError'
  examples:
    unauthorized:
      summary: The client is not authorized to perform the requested action
      value:
        code: 401
        message: '401: Request not authorized. Please provide a valid API key for access.'
    notFound:
      summary: The requested resource does not exist
      value:
        code: 404
        message: Record not found
    unprocessableEntity:
      summary: The request has missing or incorrect information
      value:
        code: 411
        message: Unable to complete the request
        errors:
        - Sample error from server
    serverError:
      summary: The server threw some kind of error or exception
      value:
        code: 500
        message: We're sorry, but something went wrong
        errors:
        - NoMethodError
        - undefined method `application' for nil:NilClass