MorphoSource-REST-API.yaml

openapi: 3.1.0
x-stoplight:
  id: rm6bqdolcidct
info:
  title: MorphoSource REST API
  version: 0.6.0
  summary: MorphoSource REST API to retrieve metadata for repository records
  contact:
    name: Julie Winchester
    url: 'https://www.morphosource.org'
    email: julie.winchester@duke.edu
  license:
    name: CC BY-NC 4.0
    url: 'https://creativecommons.org/licenses/by-nc/4.0/'
  termsOfService: 'https://www.morphosource.org/terms'
  description: |-
    # MorphoSource REST API

    [MorphoSource](https://www.morphosource.org) is a publicly accessible 3D data repository  that enables museums, researchers, and scholars to upload, curate, and share 3D and 2D media representing physical objects of scholarly importance that can be found, viewed, and downloaded by other subject experts, educators, and the public. The MorphoSource REST API allows users to query and search repository records, including Media, Physical Objects, Organizations, and media collections like Projects and Teams. Users can also use the API to download MorphoSource media. Users who manage projects and teams can use the API to retrieve usage information for media in their media collections, including numbers of downloads, download requests, and other usage statistics. 

    The API is described with intuitive human-readable [documentation](https://morphosource.stoplight.io/docs/morphosource-api/rm6bqdolcidct-morpho-source-rest-api) powered by Stoplight. This documentation includes example requests and responses which can be very helpful when getting started with the API. We also make available an [OpenAPI 3 Schema specification document](https://github.com/MorphoSource/morphosource-api) that expresses and describes the API in ways that machines can interpret.  

    ## Endpoints

    This is a list of major API endpoints that are described in this documentation, with links to pages describing each endpoint.

    ### Media

    | Endpoint | Description |
    | --- | --- |
    | [/api/media/{media-id}](https://morphosource.stoplight.io/docs/morphosource-api/b474e3d7c2ccc-get-individual-media-record) | Get individual media record |
    | [/api/media/{media-id}/file-metadata](https://morphosource.stoplight.io/docs/morphosource-api/c7dcuud1iq44q-get-individual-media-file-metadata) | Get individual media file metadata |
    | [/api/media/{media-id}/iiif/manifest](https://morphosource.stoplight.io/docs/morphosource-api/3clfct1x09z8k-get-individual-media-iiif-manifest) | Get individual media IIIF manifest |
    | [/api/media](https://morphosource.stoplight.io/docs/morphosource-api/2d534286cca2e-search-media-records) | Search media records |
    | [/api/download/{media-id}](https://morphosource.stoplight.io/docs/morphosource-api/stzmm22vruz2k-download-media-file) | Download media file |

    ### Physical Objects

    | Endpoint | Description |
    | --- | --- |
    | [/api/physical-objects/{physical-object-id}](https://morphosource.stoplight.io/docs/morphosource-api/aea3fb04ec708-get-individual-physical-object-record) | Get individual physical object record |
    | [/api/physical-objects](https://morphosource.stoplight.io/docs/morphosource-api/2da44118dab34-search-physical-object-records) | Search physical object records |

    ### Organizations

    | Endpoint | Description |
    | --- | --- |
    | [/api/organizations/{organization-id}](https://morphosource.stoplight.io/docs/morphosource-api/a544f2a31073a-get-individual-organization-record) | Get individual organization record |
    | [/api/organizations](https://morphosource.stoplight.io/docs/morphosource-api/fa3dc1d3c66be-search-organization-records) | Search organization records |

    ### Projects or Teams

    | Endpoint | Description |
    | --- | --- |
    | [/api/projects/{project-or-team-id}](https://morphosource.stoplight.io/docs/morphosource-api/a14e662377b48-get-individual-project-or-team-record) | Get individual project or team records |
    | [/api/projects](https://morphosource.stoplight.io/docs/morphosource-api/01a98fbf58a8b-search-project-or-team-records) | Search project or team records |
    | [/api/projects/{project-or-team-id}/media](https://morphosource.stoplight.io/docs/morphosource-api/12c02c9cbcce0-get-media-in-project-or-team) | Get media in project or team |
    | [/api/projects/{project-or-team-id}/biological-specimens](https://morphosource.stoplight.io/docs/morphosource-api/3bb4484b02180-get-biological-specimens-in-project-or-team) | Get biological specimens in project or team |
    | [/api/projects/{project-or-team-id}/cultural-heritage-objects](https://morphosource.stoplight.io/docs/morphosource-api/4c194247a13ee-get-cultural-heritage-objects-in-project-or-team) | Get cultural heritage objects in project or team |
    | [/api/projects/{project-or-team-id}/media-download-counts](https://morphosource.stoplight.io/docs/morphosource-api/01d554d45ad00-get-metadata-and-download-counts-of-media-in-project-or-team) | Get metadata and download counts of media in project or team |
    | [/api/projects/{project-or-team-id}/media-downloads](https://morphosource.stoplight.io/docs/morphosource-api/ecc384615696f-get-downloads-of-media-in-project-or-team) | Get downloads of media in project or team |
    | [/api/projects/{project-or-team-id}/media-requests](https://morphosource.stoplight.io/docs/morphosource-api/0e6860f269b72-get-requests-to-download-restricted-media-in-project-or-team) | Get requests to download restricted media in project or team |
    | [/api/projects/{team-id}/view-only-media-projects](https://morphosource.stoplight.io/docs/morphosource-api/67b9b4443769a-get-projects-containing-media-in-a-team-but-not-owned-by-team) | Get projects containing media in a team but not owned by team |

    ## Other Resources

    To better understand the metadata fields and terms used in the API, consult the [MorphoSource Terms Vocabulary](https://www.morphosource.org/terms/ms) and [MorphoSource Controlled Vocabularies](https://www.morphosource.org/terms/mscv) terms ontologies. These ontologies define and characterize the data model and metadata fields used by MorphoSource to record important attributes of media and physical object records, as well as the imaging and processing workflows that produce media.  

    ## Attribution

    The creation of this API documentation was supported by the National Science Foundation under Grant Number DBI-2149257. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.
servers:
  - url: 'https://www.morphosource.org'
    description: MorphoSource
paths:
  '/api/download/{media-id}':
    post:
      summary: Download media file
      operationId: post-api-download-media-id
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    x-stoplight:
                      id: 4ll5cxxqb2feb
                    properties:
                      media:
                        type: object
                        x-stoplight:
                          id: s4qe8mx5nyu88
                        properties:
                          id:
                            type: array
                            x-stoplight:
                              id: jetmccfenbrak
                            items:
                              x-stoplight:
                                id: shx8h1mrcm372
                              type: string
                          download_url:
                            type: array
                            x-stoplight:
                              id: 5xxewa82c5ja5
                            items:
                              x-stoplight:
                                id: nweu6wk70e3th
                              type: string
        '400':
          $ref: '#/components/responses/400-Bad-Request'
        '401':
          $ref: '#/components/responses/401-Authentication-Required'
        '404':
          $ref: '#/components/responses/404-Not-Found'
      x-stoplight:
        id: stzmm22vruz2k
      requestBody:
        $ref: '#/components/requestBodies/Download-Request'
      security:
        - API-Key: []
      description: |-
        Retrieves a file download URL for a single media if the user is authorized to download requested media. This endpoint can be used to achieve media file downloads using the API. Please note: this endpoint is significantly different from other routes provided by the API, so please read the description carefully. Also see the provided **Request Sample** for an example successful request.

        To use this endpoint, users must identify themselves and provide information relating to how downloaded media will be used. The following information must be supplied:
        - The media ID the user wants to download, provided as a URL path parameter.
        - The API key linked to the downloading user's MorphoSource account, provided as an authorization header.
        - A download use statement providing a free-text description of use intent at least 50 characters in length.
        - A response to a use category survey, in which the user indicates one or more specific use categories that describe the download use intent. Only certain approved use categories are allowed, see **Body** section below for allowed values. Alternately, if the use category survey allowed values do not suitably describe a user's download intent, the user can instead provide a free-text `use_category_other` that permits custom use categories to be described. One of either `use_category` or `use_category_other` must be supplied, however.  
        - User should indicate with a boolean value (`true`) that they agree to all relevant terms for download use and reuse as specified by MorphoSource and the data contributor who uploaded the media. See the particular media page on MorphoSource or query media metadata via API in order to learn more about what use restriction terms, licenses, and agreements may apply.

        If the request is successful, the response will include a direct download URL that can be used to download the media file. **Response Example** to the right demonstrates a response from a successful request. 

        Requests made to the direct download URL must still include the user's API key. The direct download URL identifies the requesting user specifically and is only to be used by the requesting user. See below for an example CURL usage to download a file from a direct download URL to a file name suggested by the API: 

        ```
        curl \
          --url "$DOWNLOAD_URL" \
          --header 'Authorization: $API_KEY' \
          --remote-name \
          --remote-header-name 
        ```
      tags:
        - Media endpoints
    parameters:
      - schema:
          type: string
        name: media-id
        in: path
        required: true
  '/api/media/{media-id}':
    get:
      summary: Get individual media record
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    description: Contains media metadata object
                    properties:
                      media:
                        $ref: '#/components/schemas/Media'
              examples: {}
        '404':
          $ref: '#/components/responses/404-Not-Found'
      operationId: get-api-media-id
      description: |-
        Returns metadata for a single Media record. 

        API key is optional. Querying published media does not require an API key. An API key can be used to query private Media the user has specific access to view. If this route is used to query a Media that does not exist, a Media that is private and the request does not supply an API key, or a Media that is private and an API key is supplied but the user does not have access to view the Media, then a 404 Not Found response will be returned.
      parameters: []
      security:
        - {}
        - API-Key: []
      tags:
        - Media endpoints
    parameters:
      - schema:
          type: string
          minLength: 9
          maxLength: 9
          example: '000200043'
        name: media-id
        in: path
        description: Unique media record ID. Should be a string of 9 numeric characters.
        required: true
  '/api/media/{media-id}/file-metadata':
    parameters:
      - schema:
          type: string
          minLength: 9
          maxLength: 9
          example: '000200043'
        name: media-id
        in: path
        required: true
        description: Unique media record ID. Should be a string of 9 numeric characters.
    get:
      summary: Get individual media file metadata
      tags:
        - Media endpoints
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    x-stoplight:
                      id: h2yncaqli83kj
                    properties:
                      file_set:
                        $ref: '#/components/schemas/Media-File-Metadata'
                        x-stoplight:
                          id: 5rweg3gxhkvxn
        '404':
          $ref: '#/components/responses/404-Not-Found'
      operationId: get-api-media-media-id-file-metadata
      x-stoplight:
        id: c7dcuud1iq44q
      description: |-
        Returns metadata specific to file object associated with a single Media record. 

        If the Media does not have an uploaded file, then an empty response will be returned: `{ "response": {} }`.

        API key is optional. Querying published media does not require an API key. An API key can be used to query private Media the user has specific access to view. If this route is used to query a Media that does not exist, a Media that is private and the request does not supply an API key, or a Media that is private and an API key is supplied but the user does not have access to view the Media, then a 404 Not Found response will be returned.
      security:
        - {}
        - API-Key: []
      parameters: []
  '/api/media/{media-id}/iiif/manifest':
    parameters:
      - schema:
          type: string
          minLength: 9
          maxLength: 9
          example: '000200043'
        name: media-id
        in: path
        required: true
        description: Unique media record ID. Should be a string of 9 numeric characters.
    get:
      summary: Get individual media IIIF manifest
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    x-stoplight:
                      id: r10c7zpz6udda
                    properties:
                      media:
                        $ref: '#/components/schemas/Media-IIIF-Manifest'
                        x-stoplight:
                          id: 02k22ahm2orbi
        '401':
          $ref: '#/components/responses/401-Authentication-Required'
        '404':
          $ref: '#/components/responses/404-Not-Found'
      operationId: get-api-media-media-id-iiif-manifest
      x-stoplight:
        id: 3clfct1x09z8k
      tags:
        - Media endpoints
      security:
        - {}
        - API-Key: []
      description: |
        Returns URL for the IIIF Presentation API manifest document for Media. Manifest is a JSON document that uses the IIIF Presentation API to provide a contextualized 3D, 2D, or AV preview of the file associated with the Media in a format suitable for use in other IIIF-compatible viewers and tools. 

        To use this endpoint, you must provide an API key associated with an active MorphoSource user account. A 401 Unauthorized response will be returned if no API key is present or if the API key is not associated with a valid user.

        Please note that IIIF Presentation manifests for private MorphoSource media will not be accessible if referenced or embedded in other viewers, only manifests of published media should be used for that use case.
  /api/media:
    get:
      summary: Search media records
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    description: Contains media metadata object
                    properties:
                      media:
                        type: array
                        items:
                          $ref: '#/components/schemas/Media'
                      facets:
                        type: array
                        items:
                          $ref: '#/components/schemas/Catalog-Facet'
                      pages:
                        $ref: '#/components/schemas/Catalog-Pages-Information'
              examples: {}
      operationId: get-api-media
      description: |-
        Searches for multiple Media records and returns metadata. A free text search query parameter is used to search across many different Media record fields. Results will be returned in paged format, with default results being returned for the first page of up to 1,000 results. Results can be filtered through the use of filter facets, which should always be supplied as query parameters in the form "f.<field_name>". See below for the list of applicable filter facet fields. This route provides equivalent functionality to the MorphoSource Media Search page (https://www.morphosource.org/catalog/media), the use of query parameters is very similar between that page and this endpoint. Experimenting with the features of the Media Search page may be instructive for use of this endpoint.

        API key is optional. Searching published media does not require an API key. An API key can be used to search private media the user has specific access to view.
      parameters:
        - schema:
            type: string
          in: query
          name: q
          description: 'Search query. This is optional, and without a query all Media matching filter facet options will be shown. Omitting query and filter information can be used to query all Media the user has access to view'
        - schema:
            type: integer
            default: 1
            format: int32
          in: query
          name: page
          description: Current results page. Displays number of results equal to per_page parameter at current page increment.
        - schema:
            type: integer
            default: 10
            maximum: 1000
            minimum: 1
            format: int32
          in: query
          name: per_page
          description: Number of results to display. Maximum value of 1000 results per page.
        - schema:
            type: string
            example: CT Image Series
          in: query
          name: f.media_type
          description: Media Type
        - schema:
            type: string
            example: MicroNanoXRayComputedTomography
          in: query
          name: f.modality
          description: Modality
        - schema:
            type: string
            example: Biological Specimen
          in: query
          name: f.object_type
          description: Object Type
        - schema:
            type: string
            example: Museum of Biological Specimens Collection of Vertebrates
          in: query
          name: f.organization
          description: Organization
        - schema:
            type: string
            example: University of Education Facility for Scanning Things
          in: query
          name: f.imaging_facility
          description: Imaging Facility
        - schema:
            type: string
            example: Open Download
          in: query
          name: f.publication_status
          description: Publication Status
        - schema:
            type: string
            example: 'http://rightsstatements.org/vocab/InC/1.0/'
          in: query
          name: f.rights_statement
          description: Rights Statement
        - schema:
            type: string
            example: 'https://creativecommons.org/licenses/by-nc/4.0/'
          in: query
          name: f.license
          description: CC License
        - schema:
            type: string
            example: Puma concolor
          in: query
          name: f.taxonomy_name
          description: Taxonomy (Name)
        - schema:
            type: string
            example: Felidae
          in: query
          name: f.taxonomy_gbif
          description: Taxonomy (GBIF)
        - schema:
            type: string
          in: query
          name: f.tag
          description: Tag
        - schema:
            type: string
          in: query
          name: f.team
          description: Team Containing Media
        - schema:
            type: string
          in: query
          name: f.project
          description: Project Containing Media
        - schema:
            type: string
          in: query
          name: f.media_list
          description: Media List Containing Media
        - schema:
            type: string
          in: query
          name: f.seq_section_list
          description: Sequential Section List Containing Media
        - schema:
            type: string
          in: query
          name: f.owner
          description: Data Manager
        - schema:
            type: string
          in: query
          name: f.depositor
          description: Data Uploader
        - schema:
            type: string
          in: query
          name: f.sponsor
          description: Data Sponsor
      security:
        - {}
        - API-Key: []
      tags:
        - Media endpoints
    parameters: []
  '/api/physical-objects/{physical-object-id}':
    get:
      summary: Get individual physical object record
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    description: Contains physical object metadata object
                    properties:
                      biological_specimen || cultural_heritage_object:
                        $ref: '#/components/schemas/Physical-Object'
              examples: {}
        '404':
          $ref: '#/components/responses/404-Not-Found'
      operationId: get-api-physical-object-id
      description: |-
        Returns metadata for a single Physical Object (Biological Specimen or Cultural Heritage Object) record.

        It is possible to include an API key, but by default all Physical Object records are public. Therefore, this is generally unnecessary.
      parameters: []
      security:
        - {}
        - API-Key: []
      tags:
        - Physical object endpoints
    parameters:
      - schema:
          type: string
          example: '000200025'
        name: physical-object-id
        in: path
        required: true
        description: Unique physical object record ID. Should be a string of 9 numeric characters.
  /api/physical-objects:
    get:
      summary: Search physical object records
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    description: Contains media metadata object
                    properties:
                      physical_objects:
                        type: array
                        items:
                          $ref: '#/components/schemas/Physical-Object'
                      facets:
                        type: array
                        items:
                          $ref: '#/components/schemas/Catalog-Facet'
                      pages:
                        $ref: '#/components/schemas/Catalog-Pages-Information'
              examples: {}
      operationId: get-api-physical-objects
      description: |-
        Searches for multiple Physical Object (Biological Specimen or Cultural Heritage Object) records and returns metadata. A free text search query parameter is used to search across many different Physical Object record fields. Results will be returned in paged format, with default results being returned for the first page of up to 1,000 results. Results can be filtered through the use of filter facets, which should always be supplied as query parameters in the form "f.<field_name>". See below for the list of applicable filter facet fields. This route provides equivalent functionality to the MorphoSource Object Search page (https://www.morphosource.org/catalog/objects), the use of query parameters is very similar between that page and this endpoint. Experimenting with the features of the Object Search page may be instructive for use of this endpoint.

        It is possible to include an API key, but by default all Physical Object records are public. Therefore, this is generally unnecessary.
      parameters:
        - schema:
            type: string
          in: query
          name: q
          description: 'Search query. This is optional, and without a query all Physical Objects matching filter facet options will be shown. Omitting query and filter information can be used to query all Physical Objects.'
        - schema:
            type: integer
            default: 1
          in: query
          name: page
          description: Current results page. Displays number of results equal to per_page parameter at current page increment.
        - schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 1000
          in: query
          name: per_page
          description: Number of results to display. Maximum value of 1000 results per page.
        - schema:
            type: string
            example: Biological Specimen
          in: query
          name: f.object_type
          description: Object Type
        - schema:
            type: string
          in: query
          name: f.creator
          description: Collector/Creator
        - schema:
            type: string
            example: Museum of Biological Specimens Collection of Vertebrates
          in: query
          name: f.organization
          description: Organization
        - schema:
            type: string
            example: Puma concolor
          in: query
          name: f.taxonomy_name
          description: Taxonomy (Name)
        - schema:
            type: string
            example: Felidae
          in: query
          name: f.taxonomy_gbif
          description: Taxonomy (GBIF)
        - schema:
            type: string
            example: CT Image Series
          in: query
          name: f.media_type
          description: Media Type
        - schema:
            type: string
          in: query
          name: f.media_tag
          description: Media Tag
        - schema:
            type: string
          in: query
          name: f.team
          description: Team Containing Media of Object
        - schema:
            type: string
          in: query
          name: f.project
          description: Project Containing Media of Object
        - schema:
            type: string
          in: query
          name: f.media_list
          description: Media List Containing Media of Object
        - schema:
            type: string
          in: query
          name: f.seq_section_list
          description: Sequential Section List Containing Media of Object
      security:
        - {}
        - API-Key: []
      tags:
        - Physical object endpoints
      requestBody:
        content: {}
    parameters: []
  '/api/organizations/{organization-id}':
    get:
      summary: Get individual organization record
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    description: Contains organization metadata object
                    properties:
                      organization:
                        $ref: '#/components/schemas/Organization'
              examples: {}
        '404':
          $ref: '#/components/responses/404-Not-Found'
      operationId: get-api-organization-id
      description: |-
        Returns metadata for a single Organization (a museum, institutional, or departmental collection of physical objects) record.

        It is possible to include an API key, but by default all Organization records are public. Therefore, this is generally unnecessary.
      parameters: []
      security:
        - {}
        - API-Key: []
      tags:
        - Organization endpoints
    parameters:
      - schema:
          type: string
          example: '000200127'
        name: organization-id
        in: path
        required: true
        description: Unique organization record ID. Should be a string of 9 numeric characters.
  /api/organizations:
    get:
      summary: Search organization records
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      organizations:
                        type: array
                        items:
                          $ref: '#/components/schemas/Organization'
                      facets:
                        type: array
                        items:
                          $ref: '#/components/schemas/Catalog-Facet'
                      pages:
                        $ref: '#/components/schemas/Catalog-Pages-Information'
              examples: {}
      operationId: get-api-organizations
      description: |-
        Searches for multiple Organization (a museum, institutional, or departmental collection of physical objects) records and returns metadata. 

        It is possible to include an API key, but by default all organization records are public. Therefore, this is generally unnecessary.
      parameters:
        - schema:
            type: string
            example: all_fields
          in: query
          name: search_field
          description: Must be "all_fields" to use search query
        - schema:
            type: string
          in: query
          name: q
          description: 'Search query. This is optional, and without a query all Organizations matching filter facet options will be shown. Omitting query and filter information can be used to query all Organizations.'
        - schema:
            type: integer
            default: 1
          in: query
          name: page
          description: Current results page. Displays number of results equal to per_page parameter at current page increment.
        - schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 1000
          in: query
          name: per_page
          description: Number of results to display. Maximum value of 1000 results per page.
        - schema:
            type: string
          in: query
          name: f.organization_type
          description: Organization Type
        - schema:
            type: string
          in: query
          name: f.institution_name
          description: Institution Name
        - schema:
            type: string
          in: query
          name: f.institution_code
          description: Institution Code
        - schema:
            type: string
          in: query
          name: f.country
          description: Country
        - schema:
            type: string
          in: query
          name: f.state_province
          description: State/Province
        - schema:
            type: string
          in: query
          name: f.city
          description: City
      security:
        - {}
        - API-Key: []
      tags:
        - Organization endpoints
    parameters: []
  '/api/projects/{project-or-team-id}':
    get:
      summary: Get individual project or team record
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    description: Contains organization metadata object
                    properties:
                      collection:
                        $ref: '#/components/schemas/Project-or-Team'
              examples: {}
        '404':
          $ref: '#/components/responses/404-Not-Found'
      operationId: get-api-project-id
      description: |-
        Returns metadata for a single Project or Team record.

        API key is optional. Querying published Projects or Teams does not require an API key. An API key can be used to query private Projects or Teams the user has specific access to view. If this route is used to query a Project or Team that does not exist, a Project or Team that is private and the request does not supply an API key, or a Project or Team that is private and an API key is supplied but the user does not have access to view the Media, then a 404 Not Found response will be returned.
      parameters: []
      security:
        - {}
        - API-Key: []
      tags:
        - Project or team endpoints
    parameters:
      - schema:
          type: string
          example: '000200022'
        name: project-or-team-id
        in: path
        required: true
        description: Unique project or team record ID. Should be a string of 9 numeric characters.
  /api/projects:
    get:
      summary: Search project or team records
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      collections:
                        type: array
                        items:
                          $ref: '#/components/schemas/Project-or-Team'
                      facets:
                        type: array
                        items:
                          $ref: '#/components/schemas/Catalog-Facet'
                      pages:
                        $ref: '#/components/schemas/Catalog-Pages-Information'
              examples: {}
      operationId: get-api-projects
      description: |-
        Searches for multiple Project or Team records and returns metadata. 

        API key is optional. Searching published Projects or Teams does not require an API key. An API key can be used to search private Projects or Teams the user has specific access to view.
      parameters:
        - schema:
            type: string
          in: query
          name: q
          description: 'Search query. This is optional, and without a query all Projects and Teams matching filter facet options will be shown. Omitting query and filter information can be used to query all Projects or Teams the user has access to view'
        - schema:
            type: integer
            default: 1
          in: query
          name: page
          description: Current results page. Displays number of results equal to per_page parameter at current page increment.
        - schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 10
          in: query
          name: per_page
          description: Number of results to display. Maximum value of 1000 results per page.
        - schema:
            type: string
          in: query
          name: f.type
          description: Project or Team
        - schema:
            type: string
          in: query
          name: f.organization
          description: Linked Organization
      security:
        - {}
        - API-Key: []
      tags:
        - Project or team endpoints
    parameters: []
  '/api/projects/{project-or-team-id}/media':
    get:
      summary: Get media in project or team
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      media:
                        type: array
                        items:
                          $ref: '#/components/schemas/Media'
              examples: {}
        '401':
          $ref: '#/components/responses/401-Authentication-Required'
        '404':
          $ref: '#/components/responses/404-Not-Found'
      operationId: get-api-project-media
      description: |-
        Returns metadata for media records in a project or team.

        To use this endpoint, you must be a manager for the project or team and provide your API key.
      parameters: []
      security:
        - API-Key: []
      tags:
        - Project or team endpoints
        - Records in project or team endpoints
    parameters:
      - schema:
          type: string
          example: '000200022'
        name: project-or-team-id
        in: path
        required: true
        description: Unique project or team record ID. Should be a string of 9 numeric characters.
  '/api/projects/{project-or-team-id}/biological-specimens':
    get:
      summary: Get biological specimens in project or team
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      objects:
                        type: array
                        items:
                          $ref: '#/components/schemas/Physical-Object'
              examples: {}
        '401':
          $ref: '#/components/responses/401-Authentication-Required'
        '404':
          $ref: '#/components/responses/404-Not-Found'
      operationId: get-api-project-biological-specimens
      description: |-
        Returns metadata for biological specimen records in a project or team.

        To use this endpoint, you must be a manager for the project or team and provide your API key.
      parameters: []
      security:
        - API-Key: []
      tags:
        - Project or team endpoints
        - Records in project or team endpoints
    parameters:
      - schema:
          type: string
          example: '000200022'
        name: project-or-team-id
        in: path
        required: true
        description: Unique project or team record ID. Should be a string of 9 numeric characters.
  '/api/projects/{project-or-team-id}/cultural-heritage-objects':
    get:
      summary: Get cultural heritage objects in project or team
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      objects:
                        type: array
                        items:
                          $ref: '#/components/schemas/Physical-Object'
                      facets:
                        type: array
                        items:
                          $ref: '#/components/schemas/Catalog-Facet'
                      pages:
                        $ref: '#/components/schemas/Catalog-Pages-Information'
              examples: {}
        '401':
          $ref: '#/components/responses/401-Authentication-Required'
        '404':
          $ref: '#/components/responses/404-Not-Found'
      operationId: get-api-project-cultural-heritage-objects
      description: |-
        Returns metadata for cultural heritage object records in a project or team.

        To use this endpoint, you must be a manager for the project or team and provide your API key.
      parameters: []
      security:
        - API-Key: []
      tags:
        - Project or team endpoints
        - Records in project or team endpoints
    parameters:
      - schema:
          type: string
          example: '000200022'
        name: project-or-team-id
        in: path
        required: true
        description: Unique project or team record ID. Should be a string of 9 numeric characters.
  '/api/projects/{project-or-team-id}/media-download-counts':
    get:
      summary: Get metadata and download counts of media in project or team
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    description: Contains organization metadata object
                    properties:
                      media_with_download_counts:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: array
                              items:
                                type: string
                            title:
                              type: array
                              items:
                                type: string
                            media:
                              $ref: '#/components/schemas/Media'
                            downloads:
                              type: array
                              items:
                                type: string
                            unique_download_users:
                              type: array
                              items:
                                type: string
                            unique_download_user_use_intent_counts:
                              $ref: '#/components/schemas/Download-Use-Intent-Category-Counts'
                            unique_download_user_demographic_counts:
                              $ref: '#/components/schemas/Download-User-Demographic-Category-Counts'
              examples: {}
        '401':
          $ref: '#/components/responses/401-Authentication-Required'
        '404':
          $ref: '#/components/responses/404-Not-Found'
      operationId: get-api-project-media-download-counts
      description: |-
        Returns numbers of downloads, download use intent and user demographics, and record metadata for media records in a project or team. This route returns media record metadata and summed counts of downloads, unique download users, and download use intent and download user demographics for each media record as a separate object. This can be compared with the `media-downloads` route, which returns each individual media download as its own separate object

        To use this endpoint, you must be a manager for the project or team and provide your API key.
      parameters: []
      security:
        - API-Key: []
      tags:
        - Project or team endpoints
        - Records in project or team endpoints
    parameters:
      - schema:
          type: string
          example: '000200022'
        name: project-or-team-id
        in: path
        required: true
        description: Unique project or team record ID. Should be a string of 9 numeric characters.
  '/api/projects/{project-or-team-id}/media-downloads':
    get:
      summary: Get downloads of media in project or team
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      media_downloads:
                        type: array
                        items:
                          $ref: '#/components/schemas/Media-Download'
              examples: {}
        '401':
          $ref: '#/components/responses/401-Authentication-Required'
        '404':
          $ref: '#/components/responses/404-Not-Found'
      operationId: get-api-project-media-downloads
      description: |-
        Returns complete information for downloads of media in a project or team. This route returns each individual media download as its own separate object. This can be compared with the `media-download-counts` route, which returns media record metadata and summed counts of downloads, unique download users, and download use intent and download user demographics for each media record as a separate object.

        To use this endpoint, you must be a manager for the project or team and provide your API key.
      parameters: []
      security:
        - API-Key: []
      tags:
        - Project or team endpoints
        - Records in project or team endpoints
    parameters:
      - schema:
          type: string
          example: '000200022'
        name: project-or-team-id
        in: path
        required: true
        description: Unique project or team record ID. Should be a string of 9 numeric characters.
  '/api/projects/{project-or-team-id}/media-requests':
    get:
      summary: Get requests to download restricted media in project or team
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      media_requests:
                        type: array
                        items:
                          $ref: '#/components/schemas/Media-Request'
              examples: {}
        '401':
          $ref: '#/components/responses/401-Authentication-Required'
        '404':
          $ref: '#/components/responses/404-Not-Found'
      operationId: get-api-project-media-requests
      description: |-
        Returns complete information for all requests to download restricted media in project or team.

        To use this endpoint, you must be a manager for the project or team and provide your API key.
      parameters: []
      security:
        - API-Key: []
      tags:
        - Project or team endpoints
        - Records in project or team endpoints
    parameters:
      - schema:
          type: string
          example: '000200022'
        name: project-or-team-id
        in: path
        required: true
        description: Unique project or team record ID. Should be a string of 9 numeric characters.
  '/api/projects/{team-id}/view-only-media-projects':
    get:
      summary: Get projects containing media in a team but not owned by team
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      collections:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: array
                              items:
                                type: string
                            title:
                              type: array
                              items:
                                type: string
                            collection:
                              $ref: '#/components/schemas/Project-or-Team'
                            url:
                              type: array
                              items:
                                type: string
                            managers:
                              type: array
                              items:
                                type: string
                            manager_emails:
                              type: array
                              items:
                                type: string
                            media_number:
                              type: array
                              items:
                                type: number
              examples: {}
        '401':
          $ref: '#/components/responses/401-Authentication-Required'
        '404':
          $ref: '#/components/responses/404-Not-Found'
      operationId: get-api-team-view-only-media-projects
      description: |-
        Some media in a team may not be owned by that team. In other words, the team may only have view access to this media. This route returns a list of projects containing media within a team that the team does not own.

        **This endpoint is only for teams - it has no functionality for projects.**

        To use this endpoint, you must be a manager for the project or team and provide your API key.
      parameters: []
      security:
        - API-Key: []
      tags:
        - Project or team endpoints
        - Records in project or team endpoints
    parameters:
      - schema:
          type: string
          example: '000200022'
        name: team-id
        in: path
        required: true
        description: Unique team record ID. Should be a string of 9 numeric characters.
components:
  schemas:
    Media:
      title: Media
      x-stoplight:
        id: kmijtc5zxqytw
      type: object
      description: 'Record for 3D, 2D, or AV media representing a physical object. This model represents the results from a search or individual record query. Some fields may only be relevant to particular media types and/or modalities, and will not pertain to all Media records.'
      properties:
        id:
          type: array
          description: "\t\nMorphosource-specific unique ID identifier for a Work (Media, Organization, Device, etc.).\nhttps://www.morphosource.org/terms/ms/ID"
          items:
            type: string
            example: '000123456'
        title:
          type: array
          description: |-
            A name given to the resource.
            http://purl.org/dc/terms/title
          items:
            type: string
            example: 'Cranium [Mesh] [Photogrammetry]'
        media_type:
          type: array
          description: "Type, nature, or classification of a Media file dataset, which may include one or more specific files. This is the general or high-level type of all file data, it is not the file type of any specific file. Most Media Types encompass a variety of different specific file types. Values must be from the Media Type controlled vocabulary (https://www.morphosource.org/terms/mscv/MediaType).\n\thttp://www.morphosource.org/terms/ms/mediaType"
          items:
            type: string
            example: Mesh
        modality:
          type: array
          description: |-
            The imaging modality used in the imaging event. Value must be from Image Modality controlled vocabulary (https://www.morphosource.org/terms/mscv/ImageModalityType).
            http://www.morphosource.org/terms/ms/ieModality
          items:
            type: string
            example: Photogrammetry
        device:
          type: array
          description: |-
            Manufacturer and model names of device used to image physical object to create media.

            Device record class: https://www.morphosource.org/terms/ms/Device
          items:
            type: string
            example: CameraCorp Camera D8500
        device_facility:
          type: array
          description: |-
            Institution and organization name for imaging facility that imaged physical object to create Media.

            Organization record class: https://www.morphosource.org/terms/ms/Organization
          items:
            type: string
            example: University of Education Imaging Facility for Scanning Things
        media_parent_id:
          type: array
          description: |-
            Morphosource-specific unique ID identifier for a Work (Media, Organization, Device, etc.). Specifically, the ID for the Media with a parental hierarchical relationship to this Media.
            https://www.morphosource.org/terms/ms/ID
          items:
            type: string
            example: '000123451'
        physical_object_id:
          type: array
          description: |-
            Morphosource-specific unique ID identifier for a Work (Media, Organization, Device, etc.). Specifically, the ID for the record of the physical object that this Media represents.
            https://www.morphosource.org/terms/ms/ID
          items:
            type: string
            example: '000104732'
        physical_object_title:
          type: array
          description: |-
            For biological specimens, the combined institution code, collection code, and catalog number separated by colons as a Darwin Core triplet. For a cultural heritage object, this is either the Darwin Core triplet or a short object tile. 
            http://purl.org/dc/terms/title
          items:
            type: string
            example: 'INST:COLL:SPEC1234'
        physical_object_organization:
          type: array
          description: |-
            Organization name of the organization that manages the physical object from which the Media was imaged.

            Organization record class: https://www.morphosource.org/terms/ms/Organization
          items:
            type: string
            example: Museum of Biological Specimens Collection of Vertebrates
        physical_object_type:
          type: array
          description: 'Type of the Object, typically "Biological Specimen" or "Cultural Heritage Object".'
          items:
            type: string
            example: Biological Specimen
        physical_object_taxonomy_name:
          type: array
          description: 'Binomial taxonomic name, in most cases a combination of genus and species names. For objects identified only with higher order taxonomy, this may take the form of a higher order name followed by "indet."'
          items:
            type: string
            x-stoplight:
              id: uafr8zm9zx65k
            example: Puma concolor
        physical_object_taxonomy_gbif:
          type: array
          description: 'List of taxonomic names associated with this physical object through a GBIF aggregated taxonomy, if one is available.'
          items:
            type: string
            x-stoplight:
              id: 0u6pb2oe3r8od
            example: Felidae
        part:
          type: array
          description: |-
            The portion or product of organism morphology, behaviour, environment, etc. that is either predominantly shown or particularly well exemplified by the media resource, denoted by an IRI.
            http://rs.tdwg.org/ac/terms/subjectPart
          items:
            type: string
            example: Cranium
        side:
          type: array
          description: |-
            The side of a larger object on which is located a represented component part, if media represents a component part of a larger whole object. Values must be from the Side controlled vocabulary (http://www.morphosource.org/terms/ms/Side). Values are somewhat oriented toward objects with bilateral symmetry, but may in some cases be applied for objects with other kinds of symmetry.
            https://www.morphosource.org/terms/ms/side
          items:
            type: string
            example: Midline
        creator:
          type: array
          description: |-
            Examples of a Creator include a person, an organization, or a service. Typically, the name of a Creator should be used to indicate the entity.

            An entity primarily responsible for making the resource.
            http://purl.org/dc/elements/1.1/creator
          items:
            type: string
            example: Jane Smith
        short_description:
          type: array
          description: |-
            Brief summary description of Media. This could include a brief summary of what is represented in the Media or the context surrounding the Media.
            https://www.morphosource.org/terms/ms/shortDescription
          items:
            type: string
            example: Mesh with texture and color of Puma concolor cranium
        description:
          type: array
          description: |-
            Description may include but is not limited to: an abstract, a table of contents, a graphical representation, or a free-text account of the resource.

            An account of the resource.
            http://purl.org/dc/elements/1.1/description
          items:
            type: string
            example: Longer description with additional context of Media scanning or identity not captured in other fields.
        ip_holder:
          type: array
          description: |-
            List of holders of intellectual property rights (copyright or license-based) for the Media.
            https://www.morphosource.org/terms/ms/rightsHolder
          items:
            type: string
            example: Museum of Biological Specimens
        copyright_statement:
          type: array
          description: |-
            Standardized rights statement used to communicate the copyright and/or reuse status of digital objects. Values must be from the Rights Statement controlled vocabulary (https://rightsstatements.org).
            https://www.morphosource.org/terms/ms/rightsStatement
          items:
            type: string
            example: 'http://rightsstatements.org/vocab/NKC/1.0/'
        license:
          type: array
          description: |-
            Recommended practice is to identify the license document with a URI. If this is not possible or feasible, a literal value that identifies the license may be provided.

            A legal document giving official permission to do something with the resource.
            http://purl.org/dc/terms/license
          items:
            type: string
            example: 'http://www.morphosource.org/terms/licenseUnknown/'
        morphosource_use_agreement_type:
          type: array
          description: |-
            Type of MorphoSource use agreement that users must agree to in order to download Media and that is packaged with an associated Media download. Values must be from the Use Agreement Type controlled vocabulary (http://www.morphosource.org/terms/mscv/UseAgreementType).
            https://www.morphosource.org/terms/ms/morphosourceUseAgreementType
          items:
            type: string
            example: Standard
        permits_commercial_use:
          type: array
          description: |
            Whether commercial use of Media is permitted. Values must be from the Commercial Use Permission controlled vocabulary (http://www.morphosource.org/terms/mscv/CommercialUsePermission).
            https://www.morphosource.org/terms/ms/permitsCommercialUse
          items:
            type: string
            example: CommercialUseNotPermitted
        permits_3d_use:
          type: array
          description: |-
            Whether Media may be 3D printed freely, may be 3D printed in limited ways, or if 3D printing is prohibited. Values must be from the 3D Printing Permission controlled vocabulary (http://www.morphosource.org/terms/mscv/3DPrintingPermission).
            https://www.morphosource.org/terms/ms/permits3DUse
          items:
            type: string
            example: 3DPrintingLimited
        required_archival_of_published_derivatives:
          type: array
          description: |-
            Whether and how future derivatives created from Media must be rearchived on a public-facing digital repository such as MorphoSource. Values may include mandatory requirements or optional suggestions. Values must be from Derivative Rearchival Statement controlled vocabulary (http://www.morphosource.org/terms/mscv/DerivativeRearchivalStatement).
            https://www.morphosource.org/terms/ms/requiredArchivalOfPublishedDerivatives
          items:
            type: string
            example: OnAnyRepository
        funding:
          type: array
          description: |-
            Text description of organizations or individuals who funded the creation of the resource.
            https://www.morphosource.org/terms/ms/funding
          items:
            type: string
            example: NSF 123456789
        publisher:
          type: array
          description: |-
            Examples of a Publisher include a person, an organization, or a service. Typically, the name of a Publisher should be used to indicate the entity.

            An entity responsible for making the resource available.
            http://purl.org/dc/elements/1.1/publisher
          items:
            type: string
        cite_as:
          type: array
          description: |-
            Instructions and guidelines for the citation of a Media. This should include additional instructions beyond those included in other metadata fields or in any download usage agreement.
            https://www.morphosource.org/terms/ms/citeAs
          items:
            type: string
        ark:
          type: array
          description: |
            Persistent identifier for MorphoSource Media automatically created on Media submission. ARKs can apply to both unpublished and published media.
            https://www.morphosource.org/terms/ms/ark
          items:
            type: string
        doi:
          type: array
          description: |-
            Persistent identifier for MorphoSource Media created only on user request. DOIs can apply only to published media.
            https://www.morphosource.org/terms/ms/doi
          items:
            type: string
        external_identifier:
          type: array
          description: |-
            Used to provide third-party or external identifiers, which may be URIs or UUIDs, for this Media.
            http://purl.org/dc/terms/identifier
          items:
            type: string
        external_media_url:
          type: array
          description: |-
            URL for additional resource that might provide additional information about the Media or Physical Object.
            https://www.morphosource.org/terms/ms/relatedURL
          items:
            type: string
        visibility:
          type: array
          description: |-
            Publication status, denoting whether or not Media may be found in public search and whether or not Media files may be downloaded. Values must be from Publication Status controlled vocabulary (http://www.morphosource.org/terms/ms/PublicationStatus).
            https://www.morphosource.org/terms/ms/visibility
          items:
            type: string
            example: Restricted
        in_collections:
          type: array
          description: Names of projects and teams to which the Media belongs.
          items:
            type: string
        date_uploaded:
          type: array
          description: |-
            Recommended practice is to describe the date, date/time, or period of time as recommended for the property Date, of which this is a subproperty.

            Date of upload of the resource.
            https://www.morphosource.org/terms/ms/dateUploaded
          items:
            type: string
            example: '2022-02-02T19:00:37Z'
        date_modified:
          type: array
          description: |-
            Recommended practice is to describe the date, date/time, or period of time as recommended for the property Date, of which this is a subproperty.

            Date on which the resource was changed.
            https://www.morphosource.org/terms/ms/dateModified
          items:
            type: string
            example: '2022-02-02T19:00:37Z'
        legacy_media_group_id:
          type: array
          description: |-
            MorphoSource-specific unique ID identifier that was used to group Media together in the now-defunct 1.0 version of the MorphoSource repository. In MorphoSource 1.0, Media groups were used to collect all media derived from the same Imaging Event. Media groups are no longer used, with media-to-media imaging and processing event relationships now being used instead to track hierarchical relationships between Media. Only present if Media was originally contributed to MorphoSource 1.0. Different from morphosource:ID identifier.
            https://www.morphosource.org/terms/ms/legacyMediaGroupID
          items:
            type: string
        legacy_media_file_id:
          type: array
          description: |-
            MorphoSource-specific unique ID identifier that was used to represent a Media in the now-defunct 1.0 version of the MorphoSource repository. Only present if Media was originally contributed to MorphoSource 1.0. Different from morphosource:ID identifier.
            https://www.morphosource.org/terms/ms/legacyMediaFileID
          items:
            type: string
        x_pixel_spacing:
          type: array
          description: |-
            Distance between centers of adjacent pixels in the X axis, for Media with pixel data where pixel spacing corresponds to real-world length measurement. Unit of measurement is described by morphosource:unit. Applies to Image and CTImageSeries media.
            https://www.morphosource.org/terms/ms/xSpacing
          items:
            type: string
            example: '0.154'
        y_pixel_spacing:
          type: array
          description: |-
            Distance between centers of adjacent pixels in the Y axis, for Media with pixel data where pixel spacing corresponds to real-world length measurement. Unit of measurement is described by morphosource:unit. Applies to Image and CTImageSeries media.
            https://www.morphosource.org/terms/ms/ySpacing
          items:
            type: string
            example: '0.154'
        z_pixel_spacing:
          type: array
          description: |-
            Distance between centers of adjacent pixels in the Z axis, for Media with 3D pixel data where pixel spacing corresponds to real-world length measurement. Unit of measurement is described by morphosource:unit. Applies to CTImageSeries media.
            http://www.morphosource.org/terms/ms/zSpacing
          items:
            type: string
            example: '0.154'
        slice_thickness:
          type: array
          description: |-
            Nominal slice thickness, in mm.
            http://purl.org/healthcarevocab/v1#SliceThickness
          items:
            type: string
        unit:
          type: array
          description: |-
            Length measurement unit. For Mesh Media, this is the length unit associated with the 3D coordinate space of the mesh. For CTImageSeries Media, this is the length unit for X/Y/Z pixel spacing. Values must be from the Length Measurement Unit controlled vocabulary (http://www.morphosource.org/terms/ms/LengthMeasurementUnit).
            https://www.morphosource.org/terms/ms/unit
          items:
            type: string
            example: Mm
        number_of_images_in_set:
          type: array
          description: |-
            For Media with a ZIP archive with many component files, this is the number of files in the primary image collection in a CT image stack or photogrammetry image collection. This only applies to CTImageSeries or PhotogrammetryImageSeries Media.
            https://www.morphosource.org/terms/ms/numberOfImagesInSet
          items:
            type: string
        data_manager:
          type: array
          description: |-
            The user that has the highest level of management control over a Media or another Work record. For Media, this user is also known as the Data Manager.
            https://www.morphosource.org/terms/ms/owner
          items:
            type: string
            example: Jane Smith
        data_depositor:
          type: array
          description: |-
            The MorphoSource user who uploaded the Media. May or may not also be the Media Data Manager.
            https://www.morphosource.org/terms/ms/depositor
          items:
            type: string
            example: Jane Smith
        data_sponsor:
          type: array
          description: The entity covering costs of data storage for this Media on MorphoSource.
          items:
            type: string
            example: Jane Smith
            x-stoplight:
              id: 9nmj5frrts1im
        file_thumbnail_url:
          type: array
          x-stoplight:
            id: jn9ihjg0ucrsp
          description: URL path of 2D thumbnail for Media.
          items:
            x-stoplight:
              id: my6vebwdo0nh2
            type: string
    Media-File-Metadata:
      title: Media-File-Metadata
      x-stoplight:
        id: 6cms9ad8zxifj
      type: object
      properties:
        file_name:
          type: array
          x-stoplight:
            id: ojbb1zjoxxjxv
          description: |-
            Identifying name label given to a file.
            https://www.morphosource.org/terms/ms/fileName
          items:
            x-stoplight:
              id: pddaai9crlejr
            type: string
        file_size:
          type: array
          x-stoplight:
            id: tal9dqyscny1d
          description: |-
            Size of a file in bytes.
            https://www.morphosource.org/terms/ms/fileSize
          items:
            x-stoplight:
              id: ulkwf00tmxwae
            type: integer
        mime_type:
          type: array
          x-stoplight:
            id: p26i4cvj7t9g2
          description: |-
            Media type describing the nature and format of a file.
            https://www.morphosource.org/terms/ms/FileSet#fileName
          items:
            x-stoplight:
              id: 03dmchmesufgc
            type: string
        point_count:
          type: array
          x-stoplight:
            id: h8uteco2uc3i6
          description: |-
            Number of 3D coordinate points comprising a 3D mesh or point cloud.
            https://www.morphosource.org/terms/ms/pointCount
          items:
            x-stoplight:
              id: x0v93tilnh5hu
            type: string
        face_count:
          type: array
          x-stoplight:
            id: 15ws5tenouht2
          description: |-
            Number of polygonal faces comprising a 3D mesh.
            https://www.morphosource.org/terms/ms/faceCount
          items:
            x-stoplight:
              id: gjcnlcwkeubc6
            type: string
        has_uv_space:
          type: array
          x-stoplight:
            id: lchypz1pwrspr
          description: |-
            Whether or not a mapping exists to project a 3D object's surface to a 2D image for texture mapping and is present with the 3D object. Values should be "Yes" or "No".
            https://www.morphosource.org/terms/ms/hasUVSpace
          items:
            x-stoplight:
              id: pwpayvqraue03
            type: string
        vertex_color:
          type: array
          x-stoplight:
            id: du6tlbxmzmujk
          description: |-
            Whether or not a 3D object has color information encoded into vertices or points that comprise a mesh or point cloud.
            https://www.morphosource.org/terms/ms/vertexColor
          items:
            x-stoplight:
              id: 2vrqinjzwxiqt
            type: string
        bounding_box_x:
          type: array
          x-stoplight:
            id: bqlxtagjz1x3j
          description: |-
            Length across the X axis of the rectangular bounding box surrounding a 3D digital object.
            https://www.morphosource.org/terms/ms/boundingBoxX
          items:
            x-stoplight:
              id: zkis9qs91au7g
            type: string
        bounding_box_y:
          type: array
          x-stoplight:
            id: aje7zz534odkn
          description: "\t\nLength across the Y axis of the rectangular bounding box surrounding a 3D digital object.\nhttps://www.morphosource.org/terms/ms/boundingBoxY"
          items:
            x-stoplight:
              id: rggu9ttdk3zbw
            type: string
        bounding_box_z:
          type: array
          x-stoplight:
            id: jss2hlc1hyeca
          description: |-
            Length across the Z axis of the rectangular bounding box surrounding a 3D digital object.
            http://www.morphosource.org/terms/ms/boundingBoxZ
          items:
            x-stoplight:
              id: ypib8ebplejtd
            type: string
        centroid_x:
          type: array
          x-stoplight:
            id: apujmfhy7sbuz
          description: |-
            X axis coordinate of the centroid of a 3D object, where the centroid is the geometric center point of the object.
            https://www.morphosource.org/terms/ms/centroidX
          items:
            x-stoplight:
              id: gk11ez6v809et
            type: string
        centroid_y:
          type: array
          x-stoplight:
            id: g61ymimi4kwbe
          description: |-
            Y axis coordinate of the centroid of a 3D object, where the centroid is the geometric center point of the object.
            https://www.morphosource.org/terms/ms/centroidY
          items:
            x-stoplight:
              id: 8q6pto32z44hw
            type: string
        centroid_z:
          type: array
          x-stoplight:
            id: 8ydharv6vatwo
          description: |-
            Z axis coordinate of the centroid of a 3D object, where the centroid is the geometric center point of the object.
            https://www.morphosource.org/terms/ms/centroidZ
          items:
            x-stoplight:
              id: rpv828c42wq7e
            type: string
        height:
          type: array
          x-stoplight:
            id: namcmmped32ne
          description: |-
            Height of a 2D image in pixels.
            https://www.morphosource.org/terms/ms/height
          items:
            x-stoplight:
              id: 7dwojxnkrecll
            type: integer
        width:
          type: array
          x-stoplight:
            id: elmdjqbj5rjms
          description: |-
            Width of a 2D image in pixels.
            https://www.morphosource.org/terms/ms/width
          items:
            x-stoplight:
              id: agdu61642l0rt
            type: integer
        color_space:
          type: array
          x-stoplight:
            id: 9sv9uwtj5nqyj
          description: |-
            Color space of image data. Values should be from the controlled vocabulary of short string labels for color spaces defined in the TIFF Tag PhotometricInterpretation (https://www.awaresystems.be/imaging/tiff/tifftags/photometricinterpretation.html).
            https://www.morphosource.org/terms/ms/colorSpace
          items:
            x-stoplight:
              id: 4bf5d6gyrocp2
            type: string
        bits_allocated:
          type: array
          x-stoplight:
            id: kiwbejdusl2zz
          description: |-
            Number of bits allocated for each pixel sample. Each sample shall have the same number of bits allocated. Bits Allocated (0028,0100) shall be either 1, or a multiple of 8. See PS3.5 for further explanation.
            http://purl.org/healthcarevocab/v1#BitsAllocated
          items:
            x-stoplight:
              id: cqebtqsy9lu5n
            type: string
        bits_per_sample:
          type: array
          x-stoplight:
            id: 75buq2qza2a0n
          description: |-
            The number of bits per image component. In this standard each component of the image is 8 bits, so the value for this tag is 8. See also SamplesPerPixel. In JPEG compressed data a JPEG marker is used instead of this tag.
            http://www.w3.org/2003/12/exif/ns#bitsPerSample
          items:
            x-stoplight:
              id: renesl44hlgq2
            type: string
        compression:
          type: array
          x-stoplight:
            id: 0q2pvnhptyq9n
          description: |-
            Compression scheme used on image data. Values should be from the controlled vocabulary of short string labels for compression schemes defined in the TIFF Tag Compression (https://www.awaresystems.be/imaging/tiff/tifftags/compression.html).
            https://www.morphosource.org/terms/ms/compression
          items:
            x-stoplight:
              id: kmq55coqlh34u
            type: string
        rows:
          type: array
          x-stoplight:
            id: br3xjuaf5qy84
          description: |-
            Number of rows in the image.

            Shall be an exact multiple of the vertical downsampling factor if any of the samples (planes) are encoded downsampled in the vertical direction for pixel data encoded in a Native (uncompressed) format. E.g., required to be an even value for a Photometric Interpretation (0028,0004) of YBR_FULL_422.

            http://purl.org/healthcarevocab/v1#Rows
          items:
            x-stoplight:
              id: hjbt7rkh920h1
            type: string
        columns:
          type: array
          x-stoplight:
            id: ta3v564em2g7w
          description: |-
            Number of columns in the image.

            Shall be an exact multiple of the horizontal downsampling factor if any of the samples (planes) are encoded downsampled in the horizontal direction for pixel data encoded in a Native (uncompressed) format. E.g., required to be an even value for a Photometric Interpretation (0028,0004) of YBR_FULL_422.

            http://purl.org/healthcarevocab/v1#Columns
          items:
            x-stoplight:
              id: iafnamvrvdf7g
            type: string
        contents_accepted_file_count:
          type: array
          x-stoplight:
            id: nz3se9nuisivy
          description: |-
            For a ZIP archive file, the largest number of system-recognized files with the same system-permissible file type located in a single directory. In MorphoSource, this is used to document the number of files in the primary image collection in a CT image stack or photogrammetry image collection.
            https://www.morphosource.org/terms/ms/contentsAcceptedFileCount
          items:
            x-stoplight:
              id: z4tn2wjbgvs7h
            type: string
        contents_file_name:
          type: array
          x-stoplight:
            id: 9lp33rf2tmdbk
          description: |-
            For a ZIP archive file, the file name of a single representative example of the largest number of system-recognized files with the same system-permissible file type located in a single directory. In MorphoSource, this is used to document a single file that is representative of the primary image collection in a CT image stack or photogrammetry image collection or the central mesh in a multi-file mesh archive.
            https://www.morphosource.org/terms/ms/contentsFileName
          items:
            x-stoplight:
              id: 0znwg2r41jzkp
            type: string
        contents_file_size:
          type: array
          x-stoplight:
            id: q0tp4z72bca9b
          description: |-
            For a ZIP archive file, the file size of a single representative example of the largest number of system-recognized files with the same system-permissible file type located in a single directory. In MorphoSource, this is used to document file size for a single file that is representative of the primary image collection in a CT image stack or photogrammetry image collection or the central mesh in a multi-file mesh archive.
            https://www.morphosource.org/terms/ms/contentsFileSize
          items:
            x-stoplight:
              id: fwk84zuikhizi
            type: string
        contents_mime_type:
          type: array
          x-stoplight:
            id: zf48lyxv8dsz5
          description: |-
            For a ZIP archive file, the mime type of a single representative example of the largest number of system-recognized files with the same system-permissible file type located in a single directory. In MorphoSource, this is used to document a single file that is representative of the primary image collection in a CT image stack or photogrammetry image collection or the central mesh in a multi-file mesh archive.
            https://www.morphosource.org/terms/ms/contentsMimeType
          items:
            x-stoplight:
              id: mq79igg1urh9k
            type: string
        date_uploaded:
          type: array
          x-stoplight:
            id: 4qkkod7u477jp
          description: |-
            Recommended practice is to describe the date, date/time, or period of time as recommended for the property Date, of which this is a subproperty.

            Date of upload of the resource.

            https://www.morphosource.org/terms/ms/dateUploaded
          items:
            x-stoplight:
              id: 4ltg2n86x91z7
            type: string
        date_modified:
          type: array
          x-stoplight:
            id: rxkircl6dvj41
          description: |-
            Recommended practice is to describe the date, date/time, or period of time as recommended for the property Date, of which this is a subproperty.

            Date on which the resource was changed.

            https://www.morphosource.org/terms/ms/dateModified
          items:
            x-stoplight:
              id: oxvz0860rftm6
            type: string
    Media-IIIF-Manifest:
      title: Media-IIIF-Manifest
      x-stoplight:
        id: ha297vet9k5i9
      type: object
      properties:
        id:
          type: string
          x-stoplight:
            id: 7w5exfo043liu
          description: |-
            Morphosource-specific unique ID identifier for a Work (Media, Organization, Device, etc.). 
            https://www.morphosource.org/terms/ms/ID
          example: '000200043'
        manifest_url:
          type: string
          x-stoplight:
            id: jmoj9zzbpv5jn
          description: URL of IIIF Presentation API manifest for Media.
      description: ''
    Physical-Object:
      title: Physical Object
      x-stoplight:
        id: ssipdqxoka4hh
      type: object
      description: Record for a physical object. This can be either a biological specimen or a cultural heritage object. This model represents the results from a search or individual record query.
      properties:
        id:
          type: array
          description: |-
            Morphosource-specific unique ID identifier for a Work (Media, Organization, Device, etc.).
            https://www.morphosource.org/terms/ms/PhysicalObject#ID
          items:
            type: string
        title:
          type: array
          description: |-
            For biological specimens, the combined institution code, collection code, and catalog number separated by colons as a Darwin Core triplet. For a cultural heritage object, this is either the Darwin Core triplet or a short object tile. 
            http://purl.org/dc/terms/title
          items:
            type: string
        organization:
          type: array
          description: |-
            Organization name of the organization that manages the physical object from which the Media was imaged.

            Organization record class: https://www.morphosource.org/terms/ms/Organization
          items:
            type: string
        institution_code:
          type: array
          description: |-
            The name (or acronym) in use by the institution having custody of the object(s) or information referred to in the record.
            http://rs.tdwg.org/dwc/terms/institutionCode
          items:
            type: string
        collection_code:
          type: array
          description: |-
            The name, acronym, coden, or initialism identifying the collection or data set from which the record was derived.
            http://rs.tdwg.org/dwc/terms/collectionCode
          items:
            type: string
        catalog_number:
          type: array
          description: |-
            An identifier (preferably unique) for the record within the data set or collection.
            http://rs.tdwg.org/dwc/terms/catalogNumber
          items:
            type: string
        occurrence_id:
          type: array
          description: |-
            Recommended best practice is to use a persistent, globally unique identifier.

            An identifier for the Occurrence (as opposed to a particular digital record of the occurrence). In the absence of a persistent global unique identifier, construct one from a combination of identifiers in the record that will most closely make the occurrenceID globally unique.
            http://rs.tdwg.org/dwc/terms/occurrenceID
          items:
            type: string
        idigbio_uuid:
          type: array
          description: |-
            Global unique identifier for the Biological Specimen provided by iDigBio and used as the primary identifier of the Biological Specimen's record in the iDigBio aggregator if present. This is sometimes used in addition to more general identifiers or Darwin Core triplets (institution code : collection code : catalog number) to uniquely identify Biological Specimen.
            https://www.morphosource.org/terms/ms/idigbioUUID
          items:
            type: string
        idigbio_recordset_id:
          type: array
          description: |-
            An identifier for an entire museum, institution, or laboratory specimen collection which includes the Biological Specimen. May be a global unique identifier or an identifier specific to a collection or institution.
            https://www.morphosource.org/terms/ms/idigbioRecordsetID
          items:
            type: string
        type:
          type: array
          description: 'Type of the Object, typically "Biological Specimen" or "Cultural Heritage Object".'
          items:
            type: string
        vouchered:
          type: array
          description: |-
            Whether the Biological Specimen is a holotype or not. If present, value must be "Yes" or "No".
            https://www.morphosource.org/terms/ms/isTypeSpecimen
          items:
            type: string
        taxonomy_name:
          type: array
          description: 'Binomial taxonomic name, in most cases a combination of genus and species names. For objects identified only with higher order taxonomy, this may take the form of a higher order name followed by "indet."'
          items:
            type: string
            x-stoplight:
              id: cybhh61iz02gf
        taxonomy_gbif:
          type: array
          description: 'List of taxonomic names associated with this physical object through a GBIF aggregated taxonomy, if one is available.'
          items:
            type: string
            x-stoplight:
              id: sue4ujsxzbp26
        sex:
          type: array
          description: |-
            Recommended best practice is to use a controlled vocabulary.

            The sex of the biological individual(s) represented in the Occurrence.
            http://rs.tdwg.org/dwc/terms/sex
          items:
            type: string
        creator:
          type: array
          description: |-
            Entity responsible for collecting or creating the object.
            http://purl.org/dc/elements/1.1/creator
          items:
            type: string
        date_uploaded:
          type: array
          description: |-
            Recommended practice is to describe the date, date/time, or period of time as recommended for the property Date, of which this is a subproperty.

            Date of upload of the resource. 
            https://www.morphosource.org/terms/ms/dateUploaded
          items:
            type: string
        date_modified:
          type: array
          description: |-
            Recommended practice is to describe the date, date/time, or period of time as recommended for the property Date, of which this is a subproperty.

            Date on which the resource was changed. 
            https://www.morphosource.org/terms/ms/dateModified
          items:
            type: string
    Catalog-Pages-Information:
      title: Catalog-Pages-Information
      x-stoplight:
        id: 5bepevvf72wt7
      type: object
      description: Catalog page information.
      properties:
        current_page:
          type: integer
        next_page:
          type:
            - integer
            - 'null'
        prev_page:
          type:
            - integer
            - 'null'
        total_pages:
          type: integer
        limit_value:
          type: integer
        offset_value:
          type: integer
        total_count:
          type: integer
        first_page?:
          type: boolean
        last_page?:
          type: boolean
    Catalog-Facet:
      title: Catalog-Facet
      x-stoplight:
        id: ka047vayvajzs
      type: object
      description: Single catalog search facet with one or more facet items.
      properties:
        name:
          type: string
        items:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              hits:
                type: integer
              label:
                type: string
        label:
          type: string
    Organization:
      title: Organization
      x-stoplight:
        id: 7vuwymxw6yg1n
      type: object
      description: 'Record for an organization (a museum, institutional, or departmental collection of physical objects). This model represents the results from a search or individual record query.'
      properties:
        id:
          type: array
          items:
            type: string
        title:
          type: array
          items:
            type: string
        date_uploaded:
          type: array
          items:
            type: string
        date_modified:
          type: array
          items:
            type: string
    Project-or-Team:
      title: Project or Team
      x-stoplight:
        id: 7vuwymxw6yg1n
      type: object
      description: Record for a project or team. This model represents the results from a search or individual record query.
      properties:
        id:
          type: array
          items:
            type: string
        project_or_team:
          type: array
          items:
            type: string
        title:
          type: array
          items:
            type: string
        linked_organization:
          type: array
          items:
            type: string
        description:
          type: array
          items:
            type: string
        creator:
          type: array
          items:
            type: string
        contributor:
          type: array
          items:
            type: string
        location:
          type: array
          items:
            type: string
        related_url:
          type: array
          items:
            type: string
        visibility:
          type: array
          items:
            type: string
        date_uploaded:
          type: array
          items:
            type: string
        date_modified:
          type: array
          items:
            type: string
    Download-Use-Intent-Category-Counts:
      title: Download Use Intent Category Counts
      x-stoplight:
        id: rk8x9ghzwsp1h
      description: Categories of use intents for media that are tracked per download.
      type: object
      properties:
        Completing Class Assignment(s) (Grades K-6):
          type: number
        Completing Class Assignment(s) (Grades 7-12):
          type: number
        Completing Class Assignment(s) (University or Post-Secondary):
          type: number
        Completing Class Assignment(s) (Post-Graduate):
          type: number
        Educator Resource (Grades K-6):
          type: number
        Educator Resource (Grades 7-12):
          type: number
        Educator Resource (University or Post-Secondary):
          type: number
        Educator Resource (Post-Graduate):
          type: number
        'Public Outreach (Museums, Documentaries, Etc)':
          type: number
        Research:
          type: number
        Art:
          type: number
        Personal Interest:
          type: number
        3D Printing:
          type: number
        Commercial Use:
          type: number
    Download-User-Demographic-Category-Counts:
      title: Download User Demographic Category Counts
      x-stoplight:
        id: cwuhtd7e24ony
      type: object
      description: Categories of user demographics that are recorded for each user for each download.
      properties:
        Student (Grades K-6):
          type: number
        Student (Grades 7-12):
          type: number
        Student (University or Post-Secondary):
          type: number
        Student (Post-Graduate):
          type: number
        Faculty (Grades K-6):
          type: number
        Faculty (Grades K-7):
          type: number
        Faculty (University or Post-Secondary):
          type: number
        Faculty (Post-Graduate):
          type: number
        University Staff:
          type: number
        General Educator:
          type: number
        Museum Curator or Collections Manager:
          type: number
        Museum Staff:
          type: number
        Librarian:
          type: number
        IT Professional:
          type: number
        Private Individual:
          type: number
        Researcher:
          type: number
        Private Industry Professional:
          type: number
        Artist:
          type: number
        Government Employee:
          type: number
    Media-Download:
      title: Media-Download
      x-stoplight:
        id: oytkqzfaeg63i
      type: object
      description: An individual download of a media record.
      properties:
        media_id:
          type: array
          items:
            type: string
        date_downloaded:
          type: array
          items:
            type: string
        download_user:
          type: array
          items:
            type: string
        download_usage:
          type: array
          items:
            type: string
        download_usage_list:
          type: array
          items:
            type: string
        download_user_id:
          type: array
          items:
            type: string
    Media-Request:
      title: Media-Request
      x-stoplight:
        id: 33thd3qbrizo9
      type: object
      description: An individual request to download media that is published with restricted download.
      properties:
        media_id:
          type: array
          items:
            type: string
        date_downloaded:
          type: array
          items:
            type: string
        date_requested:
          type: array
          items:
            type: string
        date_approved:
          type: array
          items:
            type: string
        date_denied:
          type: array
          items:
            type: string
        date_canceled:
          type: array
          items:
            type: string
        date_expired:
          type: array
          items:
            type: string
        use:
          type: array
          items:
            type: string
        date_cleared:
          type: array
          items:
            type: string
        download_user:
          type: array
          items:
            type: string
        decision_user:
          type: array
          items:
            type: string
        current_reviewers:
          type: array
          items:
            type: string
        download_user_id:
          type: array
          items:
            type: string
    Download-Use-Intent-Categories:
      title: Download-Use-Intent-Categories
      x-stoplight:
        id: 5vcwroqfq9g5w
      enum:
        - Completing Class Assignment(s) (Grades K-6)
        - Completing Class Assignment(s) (Grades 7-12)
        - Completing Class Assignment(s) (University or Post-Secondary)
        - Completing Class Assignment(s) (Post-Graduate)
        - Educator Resource (Grades K-6)
        - Educator Resource (Grades 7-12)
        - Educator Resource (University or Post-Secondary)
        - Educator Resource (Post-Graduate)
        - Research
        - Art
        - Personal Interest
        - 3D Printing
        - Commercial Use
  securitySchemes:
    API-Key:
      name: Authorization
      type: apiKey
      in: header
      description: ''
  responses:
    401-Authentication-Required:
      description: 'Standard response for authentication required. Returned in cases where an API endpoint requires an API Key associated with an existing and active MorphoSource user, but a valid API Key was not supplied with the request.'
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                default: 401
              message:
                type: string
                default: Authentication Required
              description:
                type: string
                default: You must be logged in to do that!
    404-Not-Found:
      description: 'Standard response for a resource not found, unavailable, or inaccessible by the current user.'
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                x-stoplight:
                  id: 4bq9e7t4z4y5w
                default: 404
              message:
                type: string
                x-stoplight:
                  id: 554cuhmglohbv
                default: Not Found
              description:
                type: string
                x-stoplight:
                  id: l2f5aqd71glfi
                default: Resource not found or unavailable.
    400-Bad-Request:
      description: 'Standard response for client error, most commonly because of malformed request syntax. Will include an array of specific errors encountered.'
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                x-stoplight:
                  id: ciqbvoy6usd60
                default: 400
              message:
                type: string
                x-stoplight:
                  id: ks48ly4gsw94g
                default: Bad Request
              description:
                type: string
                x-stoplight:
                  id: 7639ca587iqc2
                default: Cannot or will not process request due to perceived client error in request.
              errors:
                type: array
                x-stoplight:
                  id: k4qj0zknhzku0
                items:
                  x-stoplight:
                    id: 6gvdm5f2ksjwe
                  type: string
  requestBodies:
    Download-Request:
      content:
        application/json:
          schema:
            type: object
            properties:
              use_statement:
                type: string
                x-stoplight:
                  id: k7kfdxd8q5ptl
                minLength: 50
                example: I will use this data to complete a class assignment on primate anatomy.
              use_categories:
                type: array
                x-stoplight:
                  id: hpup9umlo1yv4
                uniqueItems: true
                minItems: 1
                items:
                  $ref: '#/components/schemas/Download-Use-Intent-Categories'
                  x-stoplight:
                    id: d0ssqbfoipi4g
              use_category_other:
                type: string
                x-stoplight:
                  id: a9wbwhgw2qodk
                example: Studying for qualifying exams
              agreements_accepted:
                type: boolean
                x-stoplight:
                  id: in26gthd215ud
            required:
              - use_statement
              - agreements_accepted
      description: |-
        - Value must be provided for EITHER use_categories OR use_category_other. For use_categories value, array values need to match Download-Use-Intent-Categories enum and at least one array value must be present.

        - As specified below in the schema, use_statement string value should be >= 50 characters.