{
  "openapi": "3.1.0",
  "info": {
    "title": "eUpdate PIVO API",
    "version": "1.6.1",
    "description": "Author: PB <pavel.bartos.pb@gmail.com>. PIVO is a local persistent identifier registry, not DOI."
  },
  "servers": [
    {
      "url": "https://update.estudium.eu"
    }
  ],
  "paths": {
    "/pivo-api.php": {
      "get": {
        "summary": "Public catalogue or record detail",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Record and revision dates, or paginated records/total/offset/limit."
          },
          "404": {
            "description": "Unknown identifier"
          }
        }
      },
      "post": {
        "summary": "Create, replace metadata or withdraw an owned record",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "enum": [
                      "create",
                      "update",
                      "withdraw"
                    ]
                  },
                  "id": {
                    "type": "string",
                    "pattern": "^PIVO-[0-9A-Z]-[0-9A-Z]{4}-[0-9A-Z]{4}$"
                  },
                  "revision": {
                    "type": "integer"
                  },
                  "idempotency_key": {
                    "type": "string"
                  },
                  "reason": {
                    "type": "string"
                  },
                  "metadata": {
                    "$ref": "#/components/schemas/Metadata"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated, withdrawn or idempotent replay"
          },
          "201": {
            "description": "New record"
          },
          "401": {
            "description": "Invalid token"
          },
          "403": {
            "description": "Not owner"
          },
          "409": {
            "description": "Conflict"
          },
          "422": {
            "description": "Invalid metadata"
          },
          "429": {
            "description": "Rate limit"
          }
        }
      }
    },
    "/article-api.php": {
      "get": {
        "summary": "Public deduplicated article catalogue and monthly top nine, or detail with citations",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "author",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "organization",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "month",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Article list or detail"
          },
          "404": {
            "description": "Private or missing record"
          }
        }
      }
    },
    "/citation.php": {
      "get": {
        "summary": "Download a formatted citation",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "enum": [
                "apa",
                "ieee",
                "iso690",
                "bibtex",
                "ris"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Citation attachment"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Metadata": {
        "type": "object",
        "required": [
          "title",
          "authors",
          "publication_date",
          "abstract",
          "keywords"
        ],
        "description": "Requires url or an owned uploaded file_id. Updates replace complete metadata.",
        "properties": {
          "title": {
            "type": "string"
          },
          "authors": {
            "type": "string"
          },
          "year": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "file_id": {
            "type": "string"
          },
          "publisher": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "abstract": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "license": {
            "type": "string"
          },
          "isbn": {
            "type": "string"
          },
          "issn": {
            "type": "string"
          },
          "doi": {
            "type": "string"
          },
          "scholar_url": {
            "type": "string"
          },
          "publication_date": {
            "type": "string",
            "description": "YYYY-MM or MM/YYYY"
          },
          "keywords": {
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "maxItems": 30
              },
              {
                "type": "string"
              }
            ],
            "description": "Up to 30 keywords, max 100 characters each. Use an array or a semicolon-separated string; commas are preserved within a keyword."
          },
          "journal": {
            "type": "string"
          },
          "volume": {
            "type": "string"
          },
          "issue": {
            "type": "string"
          },
          "pages": {
            "type": "string"
          }
        }
      }
    }
  }
}