openapi: 3.0.3
info:
  title: OpenCitations Index REST Authors References API
  description: 'REST API for accessing the data stored in the OpenCitations Index. Provides operations to retrieve citation data for references to other works appearing in a particular bibliographic entity, or citation data for references in other works to a particular bibliographic entity, given the identifier of a bibliographic entity, or to retrieve citation data about a particular citation identified by means of its Open Citation Identifier (OCI).

    All operations return either a JSON document (default) or a CSV document according to the mimetype specified in the Accept header of the request.

    API calls are rate-limited to 180 requests/minute per IP address. For large-scale retrieval use the database dumps at download.opencitations.net.

    '
  version: 2.2.0
  contact:
    name: OpenCitations
    email: contact@opencitations.net
    url: https://opencitations.net
  license:
    name: Creative Commons Attribution 4.0 International
    url: https://creativecommons.org/licenses/by/4.0/legalcode
  x-api-created: '2025-04-15'
servers:
- url: https://api.opencitations.net/index/v2
  description: OpenCitations Index API v2
security:
- accessToken: []
- {}
tags:
- name: References
  description: Operations for retrieving outgoing reference data
paths:
  /reference-count/{id}:
    get:
      summary: Get outgoing reference count
      operationId: getReferenceCount
      description: 'Retrieves the number of outgoing citations from the bibliographic entity identified by the input PID (DOI, PMID, OMID, or ISSN).

        '
      tags:
      - References
      parameters:
      - name: id
        in: path
        required: true
        description: 'PID of the bibliographic entity. Must be prefixed with identifier type: doi:, pmid:, omid:, or issn:

          '
        schema:
          type: string
          pattern: ^(omid|doi|pmid|issn):.+
          example: doi:10.7717/peerj-cs.421
      - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Outgoing citation count
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Count'
              example:
              - count: '35'
            text/csv:
              schema:
                type: string
  /references/{id}:
    get:
      summary: Get outgoing references
      operationId: getReferences
      description: 'Retrieves citation data for all outgoing references to other cited works appearing in the reference list of the bibliographic entity identified by the input PID (DOI, PMID, or OMID).

        Fields returned: oci, citing, cited, creation, timespan, journal_sc, author_sc.

        '
      tags:
      - References
      parameters:
      - name: id
        in: path
        required: true
        description: 'PID of the bibliographic entity. Must be prefixed with identifier type: doi:, pmid:, or omid:

          '
        schema:
          type: string
          pattern: ^(omid|doi|pmid):.+
          example: doi:10.7717/peerj-cs.421
      - $ref: '#/components/parameters/require'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/json'
      responses:
        '200':
          description: Outgoing references
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Citation'
            text/csv:
              schema:
                type: string
components:
  schemas:
    Count:
      type: object
      description: Citation or reference count result
      properties:
        count:
          type: string
          description: Number of citations or references
          example: '34'
    Citation:
      type: object
      description: Citation metadata record
      properties:
        oci:
          type: string
          description: Open Citation Identifier (OCI) of the citation
          example: 06101801781-06180334099
        citing:
          type: string
          description: Space-separated PIDs of the citing entity (prefixed with index name)
          example: omid:br/06101801781 doi:10.7717/peerj-cs.421 pmid:33817056
        cited:
          type: string
          description: Space-separated PIDs of the cited entity (prefixed with index name)
          example: omid:br/06180334099 doi:10.1108/jd-12-2013-0166
        creation:
          type: string
          format: date
          description: Creation date of the citation (ISO 8601 YYYY-MM-DD)
          example: '2021-03-10'
        timespan:
          type: string
          description: Interval between publication dates in XSD duration format (PnYnMnD)
          example: P6Y0M1D
        journal_sc:
          type: string
          enum:
          - true
          - false
          description: Whether the citation is a journal self-citation
          example: 'no'
        author_sc:
          type: string
          enum:
          - true
          - false
          description: Whether the citation is an author self-citation
          example: 'no'
  parameters:
    filter:
      name: filter
      in: query
      required: false
      description: 'Applies conditional filtering. Supports regex or operators (=, <, >). Format: field:operator:value. Example: date:>2015

        '
      schema:
        type: string
        example: date:>2015
    format:
      name: format
      in: query
      required: false
      description: Output format. Accepts "csv" or "json" (default).
      schema:
        type: string
        enum:
        - json
        - csv
        default: json
    sort:
      name: sort
      in: query
      required: false
      description: 'Orders results by field in ascending or descending order. Format: asc(field) or desc(field).

        '
      schema:
        type: string
        example: desc(date)
    json:
      name: json
      in: query
      required: false
      description: 'Transforms JSON data structure. Supports array splitting or dict conversion.

        '
      schema:
        type: string
    require:
      name: require
      in: query
      required: false
      description: Removes rows with empty values in the specified field
      schema:
        type: string
        example: doi
  securitySchemes:
    accessToken:
      type: apiKey
      in: header
      name: authorization
      description: 'OpenCitations Access Token obtained from https://opencitations.net/accesstoken. Recommended for application/code usage to ensure stable access.

        '
externalDocs:
  description: OpenCitations Index API Documentation
  url: https://api.opencitations.net/index/v2