{
  "openapi": "3.1.0",
  "info": {
    "title": "Evident Source Check",
    "version": "1.0.0",
    "description": "Public reference metadata checking for people and Agents. No truth score; see result limitations."
  },
  "servers": [
    {
      "url": "https://evidentagents.com"
    }
  ],
  "paths": {
    "/api/v3/references/check": {
      "post": {
        "operationId": "checkReferences",
        "summary": "Check public DOI/arXiv bibliographic metadata",
        "description": "No account. Only public references. HTTP 200 may include inconclusive items; read every status. Existence is not claim support. search_titles:true forwards public title-only entries to Crossref.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 10000,
                    "description": "Public references, one per line. DOI, arXiv URL/ID, or Title | DOI | Year. Do not send private drafts."
                  },
                  "references": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 10,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "doi": {
                          "type": "string",
                          "maxLength": 200
                        },
                        "arxiv": {
                          "type": "string",
                          "maxLength": 100
                        },
                        "title": {
                          "type": "string",
                          "maxLength": 400
                        },
                        "year": {
                          "type": "integer",
                          "minimum": 1000,
                          "maximum": 2100
                        }
                      }
                    }
                  },
                  "search_titles": {
                    "type": "boolean",
                    "default": false,
                    "description": "Explicitly allow sending public title-only entries to Crossref to find candidates. Candidates are not verified identity matches."
                  }
                },
                "oneOf": [
                  {
                    "required": [
                      "text"
                    ],
                    "not": {
                      "required": [
                        "references"
                      ]
                    }
                  },
                  {
                    "required": [
                      "references"
                    ],
                    "not": {
                      "required": [
                        "text"
                      ]
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Metadata report with explicit per-reference outcomes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "schema_version",
                    "checked_at",
                    "summary",
                    "results",
                    "limitations",
                    "privacy"
                  ],
                  "properties": {
                    "schema_version": {
                      "type": "string"
                    },
                    "checked_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "summary": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "record_found": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "metadata_differs": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "not_found": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "inconclusive": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "candidates_only": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "needs_identifier": {
                          "type": "integer",
                          "minimum": 0
                        }
                      }
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "position",
                          "input",
                          "status"
                        ],
                        "properties": {
                          "position": {
                            "type": "integer"
                          },
                          "input": {
                            "type": "object"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "record_found",
                              "metadata_differs",
                              "not_found",
                              "inconclusive",
                              "candidates_only",
                              "needs_identifier"
                            ]
                          },
                          "comparison": {
                            "type": "object",
                            "properties": {
                              "title": {
                                "type": "string",
                                "enum": [
                                  "matches",
                                  "differs",
                                  "not_supplied"
                                ]
                              },
                              "year": {
                                "type": "string",
                                "enum": [
                                  "matches",
                                  "differs",
                                  "not_supplied",
                                  "unknown"
                                ]
                              }
                            }
                          },
                          "record": {
                            "type": "object",
                            "description": "Public record only; contains DOI, title, authors, publication years, registry, metadata_url and DOI url."
                          },
                          "candidates": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          },
                          "attempts": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          },
                          "retrieved_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "cached": {
                            "type": "boolean"
                          },
                          "note": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "privacy": {
                      "type": "object"
                    },
                    "method_url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request too large"
          },
          "422": {
            "description": "Invalid input"
          },
          "429": {
            "description": "Capacity exceeded; honor Retry-After"
          },
          "503": {
            "description": "Checking unavailable"
          }
        },
        "security": []
      }
    },
    "/api/v3/references/schema": {
      "get": {
        "operationId": "referenceCheckSchema",
        "summary": "Read input schema and current limits",
        "responses": {
          "200": {
            "description": "Input contract and limits"
          }
        },
        "security": []
      }
    }
  }
}