Crossref Types API

openapi: 3.2.0
info:
  title: Crossref Types API
  description: The Crossref REST API is one of a variety of tools and APIs that allow anybody to search and reuse our members' metadata in sophisticated ways.
  contact:
    name: Crossref
    url: https://crossref.org
    email: support@crossref.org
  version: 3.32.0
servers:
- url: /
tags:
- name: Types
  description: Endpoints that expose type related data
paths:
  /types/{id}:
    get:
      tags:
      - Types
      description: Returns information about a metadata work type, as an example use `monograph`
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: The type identified by {id}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TypeMessage'
        '404':
          description: The type identified by {id} does not exist.
          content: {}
      summary: Get types by id
      x-summary-source: derived
      operationId: getTypesById
      x-operation-id-source: derived
  /types:
    get:
      tags:
      - Types
      description: 'Returns a list of valid work types.

        ## Pagination with offsets


        Offsets can be used to iterate over the results. For this route, the maximum number of available results is 80,000, which in this case allows to retrieve all the indexed items. This limit applies to the sum of values of parameters `offset` + `rows`.


        ##


        The number of items returned in a single response is controlled by `rows` parameter (default is 20, and maximum is 1,000). To limit results to 5, for example, you could do the following:


        ##


        ```

        /works?query=allen+renear&rows=5

        ```


        ##


        `offset` parameter can be used to retrieve items starting from a specific index of the result list. For example, to select the second set of 5 results (i.e. results 6 through 10), you would do the following:


        ##


        ```

        /works?query=allen+renear&rows=5&offset=5

        ```


        ##'
      parameters:
      - name: rows
        in: query
        description: The number of rows per page
        schema:
          type: integer
          format: int64
      - name: mailto
        in: query
        description: The email address to identify yourself and be in the "polite pool"
        schema:
          pattern: ^[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+\.[A-Za-z]{2,6}$
          type: string
      - name: offset
        in: query
        description: The number of rows to skip before returning
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: A collection of types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TypesMessage'
      summary: Get types
      x-summary-source: derived
      operationId: getTypes
      x-operation-id-source: derived
  /types/{id}/works:
    get:
      tags:
      - Types
      description: returns list of works of type {id}.
      parameters:
      - name: rows
        in: query
        description: The number of rows per page
        schema:
          type: integer
          format: int64
      - name: order
        in: query
        description: Combined with sort can be used to specify the order of results, e.g. asc or desc
        schema:
          pattern: (asc|desc)
          type: string
      - name: facet
        in: query
        description: Exposes the ability to retrieve counts for pre-defined facets e.g. `type-name:*` returns counts of all works by type
        schema:
          type: string
      - name: sample
        in: query
        description: Exposes the ability to return `N` randomly sampled items
        schema:
          type: integer
          format: int64
      - name: sort
        in: query
        description: Exposes the ability to sort results by a certain field, e.g. `score`
        schema:
          type: string
      - name: offset
        in: query
        description: The number of rows to skip before returning
        schema:
          type: integer
          format: int64
      - name: mailto
        in: query
        description: The email address to identify yourself and be in the "polite pool"
        schema:
          pattern: ^[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+\.[A-Za-z]{2,6}$
          type: string
      - name: select
        in: query
        description: Exposes the ability to select certain fields, supports a comma separated list of fields, e.g. `DOI,volume`
        schema:
          pattern: ^\w+(,\w+)*$
          type: string
      - name: query
        in: query
        description: Exposes the ability to free text query certain fields
        schema:
          type: string
      - name: filter
        in: query
        description: Exposes the ability to filter by certain fields, supports a comma separated list of lucene filters, e.g. `content-domain:psychoceramics.labs.crossref.org`
        schema:
          type: string
      - name: cursor
        in: query
        description: Exposes the ability to deep page through large result sets, where offset would cause performance problems
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: A list of works
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorksMessage'
      summary: Get types by id works
      x-summary-source: derived
      operationId: getTypesByIdWorks
      x-operation-id-source: derived
components:
  schemas:
    WorkAssertionExplanation:
      required:
      - URL
      type: object
      properties:
        URL:
          type: string
      additionalProperties: false
    WorkStandardsBody:
      type: object
      properties:
        name:
          type: string
        acronym:
          type: array
          items:
            type: string
      additionalProperties: false
    WorkLink:
      required:
      - URL
      - content-type
      - content-version
      - intended-application
      type: object
      properties:
        URL:
          type: string
        content-type:
          type: string
        content-version:
          type: string
        intended-application:
          type: string
      additionalProperties: false
    WorkFreeToRead:
      type: object
      properties:
        start-date:
          $ref: '#/components/schemas/DateParts'
        end-date:
          $ref: '#/components/schemas/DateParts'
      additionalProperties: false
    DateParts:
      required:
      - date-parts
      type: object
      properties:
        date-parts:
          type: array
          items:
            type: array
            items:
              type: integer
              format: int64
      additionalProperties: false
    VersionInfo:
      required:
      - version
      type: object
      properties:
        version:
          type: string
        language:
          type: string
        version-description:
          type: array
          items:
            $ref: '#/components/schemas/VersionInfoDescription'
      additionalProperties: false
    WorkRelation:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/WorkRelationObject'
    Query:
      required:
      - search-terms
      - start-index
      type: object
      properties:
        start-index:
          type: integer
          format: int64
        search-terms:
          type: string
      additionalProperties: false
    WorkReview:
      type: object
      properties:
        type:
          type: string
        running-number:
          type: string
        revision-round:
          type: string
        stage:
          type: string
        competing-interest-statement:
          type: string
        recommendation:
          type: string
        language:
          type: string
      additionalProperties: false
    WorkISSNType:
      required:
      - type
      - value
      type: object
      properties:
        type:
          type: string
        value:
          type: array
          items:
            type: string
      additionalProperties: false
    Reference:
      type: object
      properties:
        issn:
          type: string
        standards-body:
          type: string
        issue:
          type: string
        key:
          type: string
        series-title:
          type: string
        isbn-type:
          type: string
        doi-asserted-by:
          type: string
        first-page:
          type: string
        type:
          type: string
        isbn:
          type: string
        doi:
          type: string
        component:
          type: string
        article-title:
          type: string
        volume-title:
          type: string
        volume:
          type: string
        author:
          type: string
        standard-designator:
          type: string
        year:
          type: string
        unstructured:
          type: string
        edition:
          type: string
        journal-title:
          type: string
        issn-type:
          type: string
      additionalProperties: false
    WorkDomain:
      required:
      - domain
      type: object
      properties:
        domain:
          type: array
          items:
            type: string
        crossmark-restriction:
          type: boolean
      additionalProperties: false
    WorksMessage:
      required:
      - message
      - message-type
      - message-version
      - status
      type: object
      properties:
        status:
          type: string
        message-type:
          pattern: work-list
          type: string
        message-version:
          type: string
        message:
          $ref: '#/components/schemas/Works'
      additionalProperties: false
    Type:
      required:
      - id
      - label
      type: object
      properties:
        id:
          type: string
        label:
          type: string
      additionalProperties: false
    Types:
      required:
      - items
      - items-per-page
      - query
      - total-results
      type: object
      properties:
        items-per-page:
          type: integer
          format: int64
        query:
          $ref: '#/components/schemas/Query'
        total-results:
          type: integer
          format: int64
        items:
          type: array
          items:
            $ref: '#/components/schemas/Type'
      additionalProperties: false
    WorkClinicalTrial:
      required:
      - clinical-trial-number
      - registry
      type: object
      properties:
        clinical-trial-number:
          type: string
        registry:
          type: string
        type:
          type: string
      additionalProperties: false
    WorkLicense:
      required:
      - URL
      - content-version
      - delay-in-days
      type: object
      properties:
        URL:
          type: string
        start:
          $ref: '#/components/schemas/Date'
        delay-in-days:
          type: integer
          format: int64
        content-version:
          type: string
      additionalProperties: false
    Affiliation:
      required:
      - name
      type: object
      properties:
        name:
          type: string
      additionalProperties: false
    WorkFunder:
      type: object
      properties:
        name:
          type: string
        DOI:
          type: string
        doi-asserted-by:
          type: string
        award:
          type: array
          items:
            type: string
        id:
          type: array
          items:
            $ref: '#/components/schemas/FunderIdentifier'
      additionalProperties: false
    TypeMessage:
      required:
      - message
      - message-type
      - message-version
      - status
      type: object
      properties:
        status:
          type: string
        message-type:
          pattern: type
          type: string
        message-version:
          type: string
        message:
          $ref: '#/components/schemas/Type'
      additionalProperties: false
    FunderIdentifier:
      required:
      - asserted-by
      - id
      - id-type
      type: object
      properties:
        id:
          type: string
        id-type:
          type: string
        asserted-by:
          type: string
      additionalProperties: false
    WorkRelationObject:
      required:
      - asserted-by
      - id
      - id-type
      type: object
      properties:
        id-type:
          type: string
        id:
          type: string
        asserted-by:
          type: string
      additionalProperties: false
    WorkInstitution:
      required:
      - name
      type: object
      properties:
        name:
          type: string
        place:
          type: array
          items:
            type: string
        department:
          type: array
          items:
            type: string
        acronym:
          type: array
          items:
            type: string
      additionalProperties: false
    Work:
      required:
      - DOI
      - URL
      - created
      - deposited
      - indexed
      - issued
      - member
      - prefix
      - publisher
      - resource
      - score
      - source
      - type
      type: object
      properties:
        institution:
          type: array
          items:
            $ref: '#/components/schemas/WorkInstitution'
        indexed:
          $ref: '#/components/schemas/DateAndVersion'
        posted:
          $ref: '#/components/schemas/DateParts'
        publisher-location:
          type: string
        update-to:
          type: array
          items:
            $ref: '#/components/schemas/WorkUpdate'
        standards-body:
          type: array
          items:
            $ref: '#/components/schemas/WorkStandardsBody'
        edition-number:
          type: string
        group-title:
          type: array
          items:
            type: string
        reference-count:
          type: integer
          format: int64
        publisher:
          type: string
        issue:
          type: string
        isbn-type:
          type: array
          items:
            $ref: '#/components/schemas/WorkISSNType'
        license:
          type: array
          items:
            $ref: '#/components/schemas/WorkLicense'
        funder:
          type: array
          items:
            $ref: '#/components/schemas/WorkFunder'
        content-domain:
          $ref: '#/components/schemas/WorkDomain'
        chair:
          type: array
          items:
            $ref: '#/components/schemas/Author'
        short-container-title:
          type: string
        accepted:
          $ref: '#/components/schemas/DateParts'
        content-updated:
          $ref: '#/components/schemas/DateParts'
        published-print:
          $ref: '#/components/schemas/DateParts'
        abstract:
          type: string
        DOI:
          type: string
          description: The DOI identifier associated with the work
        type:
          type: string
        created:
          $ref: '#/components/schemas/Date'
        approved:
          $ref: '#/components/schemas/DateParts'
        page:
          type: string
        update-policy:
          type: string
        source:
          type: string
        is-referenced-by-count:
          type: integer
          format: int64
        title:
          type: array
          items:
            type: string
        prefix:
          type: string
        volume:
          type: string
        clinical-trial-number:
          type: array
          items:
            $ref: '#/components/schemas/WorkClinicalTrial'
        author:
          type: array
          items:
            $ref: '#/components/schemas/Author'
        member:
          type: string
        content-created:
          $ref: '#/components/schemas/DateParts'
        published-online:
          $ref: '#/components/schemas/DateParts'
        reference:
          $ref: '#/components/schemas/Reference'
        container-title:
          type: array
          items:
            type: string
        review:
          $ref: '#/components/schemas/WorkReview'
        original-title:
          type: array
          items:
            type: string
        language:
          type: string
        link:
          type: array
          items:
            $ref: '#/components/schemas/WorkLink'
        deposited:
          $ref: '#/components/schemas/Date'
        score:
          type: integer
          format: int64
        degree:
          type: string
        resource:
          $ref: '#/components/schemas/Resources'
        subtitle:
          type: array
          items:
            type: string
        translator:
          type: array
          items:
            $ref: '#/components/schemas/Author'
        free-to-read:
          $ref: '#/components/schemas/WorkFreeToRead'
        editor:
          type: array
          items:
            $ref: '#/components/schemas/Author'
        proceedings-subject:
          type: string
        component-number:
          type: string
        short-title:
          type: array
          items:
            type: string
        issued:
          $ref: '#/components/schemas/DateParts'
        ISBN:
          type: array
          items:
            type: string
        references-count:
          type: integer
          format: int64
        part-number:
          type: string
        issue-title:
          type: array
          items:
            type: string
        journal-issue:
          $ref: '#/components/schemas/WorkJournalIssue'
        alternative-id:
          type: array
          items:
            type: string
        version:
          $ref: '#/components/schemas/VersionInfo'
        URL:
          type: string
        archive:
          type: array
          items:
            type: string
        relation:
          $ref: '#/components/schemas/WorkRelation'
        ISSN:
          type: array
          items:
            type: string
        issn-type:
          type: array
          items:
            $ref: '#/components/schemas/WorkISSNType'
        subject:
          type: array
          items:
            type: string
        published-other:
          $ref: '#/components/schemas/DateParts'
        published:
          $ref: '#/components/schemas/DateParts'
        assertion:
          type: array
          items:
            $ref: '#/components/schemas/WorkAssertion'
        subtype:
          type: string
        article-number:
          type: string
      additionalProperties: false
    DateAndVersion:
      required:
      - date-parts
      - date-time
      - timestamp
      - version
      type: object
      properties:
        date-parts:
          type: array
          items:
            type: array
            items:
              type: integer
              format: int64
        date-time:
          type: string
          format: date-time
        timestamp:
          type: integer
          format: int64
        version:
          type: string
      additionalProperties: false
    WorkUpdate:
      required:
      - DOI
      - label
      - type
      - updated
      type: object
      properties:
        label:
          type: string
        DOI:
          type: string
        type:
          type: string
        updated:
          $ref: '#/components/schemas/Date'
      additionalProperties: false
    TypesMessage:
      required:
      - message
      - message-type
      - message-version
      - status
      type: object
      properties:
        status:
          type: string
        message-type:
          pattern: type-list
          type: string
        message-version:
          type: string
        message:
          $ref: '#/components/schemas/Types'
      additionalProperties: false
    Works:
      required:
      - items
      - items-per-page
      - query
      - total-results
      type: object
      properties:
        items-per-page:
          type: integer
          format: int64
        query:
          $ref: '#/components/schemas/Query'
        total-results:
          type: integer
          format: int64
        next-cursor:
          type: string
          description: Used to navigate to the next page of results when using cursor deep paging
        items:
          type: array
          items:
            $ref: '#/components/schemas/Work'
      additionalProperties: false
    Resources:
      required:
      - primary
      type: object
      properties:
        primary:
          $ref: '#/components/schemas/PrimaryResource'
        secondary:
          type: array
          items:
            $ref: '#/components/schemas/SecondaryResource'
      additionalProperties: false
    PrimaryResource:
      required:
      - URL
      type: object
      properties:
        URL:
          type: string
      additionalProperties: false
    WorkAssertion:
      required:
      - name
      type: object
      properties:
        group:
          $ref: '#/components/schemas/WorkAssertionGroup'
        explanation:
          $ref: '#/components/schemas/WorkAssertionExplanation'
        name:
          type: string
        value:
          type: string
        URL:
          type: string
        order:
          type: integer
          format: int64
      additionalProperties: false
    WorkAssertionGroup:
      required:
      - name
      type: object
      properties:
        name:
          type: string
        label:
          type: string
      additionalProperties: false
    SecondaryResource:
      required:
      - URL
      - label
      type: object
      properties:
        URL:
          type: string
        label:
          type: string
      additionalProperties: false
    Author:
      required:
      - affiliation
      - sequence
      type: object
      properties:
        ORCID:
          type: string
        suffix:
          type: string
        given:
          type: string
        family:
          type: string
        affiliation:
          type: array
          items:
            $ref: '#/components/schemas/Affiliation'
        name:
          type: string
        authenticated-orcid:
          type: boolean
        prefix:
          type: string
        sequence:
          type: string
      additionalProperties: false
    Date:
      required:
      - date-parts
      - date-time
      - timestamp
      type: object
      properties:
        date-parts:
          type: array
          items:
            type: array
            items:
              type: integer
              format: int64
        date-time:
          type: string
          format: date-time
        timestamp:
          type: integer
          format: int64
      additionalProperties: false
    VersionInfoDescription:
      type: object
      properties:
        language:
          type: string
        description:
          type: string
      additionalProperties: false
    WorkJournalIssue:
      required:
      - issue
      type: object
      properties:
        issue:
          type: string
      additionalProperties: false
x-original-swagger-version: '2.0'