{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/pepbank-io/json-schema/pepbank-io-finding-search-response-schema.json",
  "title": "FindingSearchResponse",
  "description": "Checked findings (layer 1). included holds the cited publications and source sentences.",
  "x-generated": "2026-11-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/pepbank-io-openapi.json#/components/schemas/FindingSearchResponse",
  "type": "object",
  "properties": {
    "credit": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "enum": [
            "Data from PepBank"
          ]
        },
        "line": {
          "type": "string",
          "description": "Credit sentence. Copy it as written."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "PepBank page for this result. The home page applies when no single page fits."
        },
        "license_url": {
          "type": "string",
          "enum": [
            "https://creativecommons.org/licenses/by/4.0/"
          ]
        }
      },
      "required": [
        "text",
        "url",
        "license_url"
      ]
    },
    "record_type": {
      "type": "string",
      "enum": [
        "search_response"
      ]
    },
    "query_id": {
      "type": "string",
      "description": "ID of the normalized query at this data_seq. GET /v1/queries/{query_id} replays it."
    },
    "data_seq": {
      "type": "integer",
      "description": "Change-feed position that every page of this search reads."
    },
    "request": {
      "type": "object",
      "properties": {
        "entity": {
          "type": "string",
          "enum": [
            "peptides",
            "publications",
            "findings",
            "trials",
            "community_reports"
          ]
        },
        "text": {
          "type": [
            "string",
            "null"
          ]
        },
        "filters": {
          "type": "object",
          "additionalProperties": {}
        },
        "sort": {
          "type": "string"
        },
        "as_of_seq": {
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "required": [
        "entity",
        "text",
        "filters",
        "sort",
        "as_of_seq"
      ]
    },
    "total_count": {
      "type": "integer",
      "minimum": 0,
      "description": "Exact number of results."
    },
    "returned": {
      "type": "integer",
      "minimum": 0
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cursor for the next page. Null on the last page."
    },
    "complete": {
      "type": "boolean",
      "description": "True on the last page when nothing was withheld."
    },
    "result_set_hash": {
      "type": [
        "string",
        "null"
      ],
      "description": "SHA-256 of the ordered result IDs, joined by newline. Present on the last page."
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "record_type": {
            "type": "string",
            "enum": [
              "finding"
            ]
          },
          "finding_id": {
            "type": "string"
          },
          "publication_id": {
            "type": "string"
          },
          "peptide": {
            "type": "object",
            "properties": {
              "peptide_id": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "peptide_id"
            ],
            "additionalProperties": {}
          },
          "evidence_class": {
            "type": "string",
            "enum": [
              "human",
              "animal",
              "laboratory",
              "predicted"
            ],
            "description": "Evidence class: human, animal, laboratory or predicted."
          },
          "evidence_detail": {
            "type": "object",
            "properties": {
              "design": {
                "type": "string"
              }
            },
            "required": [
              "design"
            ],
            "additionalProperties": {}
          },
          "claim": {
            "type": "object",
            "properties": {
              "claim_type": {
                "type": "string"
              },
              "outcome": {
                "type": "string"
              },
              "direction": {
                "type": "string"
              },
              "statement": {
                "type": "string"
              },
              "statement_plain": {
                "type": "string",
                "description": "Plain-language restatement for non-specialists (v0.3). It adds no facts."
              },
              "outcome_group": {
                "type": "string",
                "description": "Normalized outcome group, for example Wound healing (v0.3)."
              },
              "body_system": {
                "type": "string",
                "description": "Body system, for example Musculoskeletal (v0.3)."
              },
              "peptide_role": {
                "type": "string",
                "enum": [
                  "administered",
                  "endogenous_level",
                  "other"
                ],
                "description": "Role of the peptide in the study (extraction prompt v0.4). Only administered findings are evidence about taking the peptide. endogenous_level findings measure the body's own peptide."
              }
            },
            "additionalProperties": {}
          },
          "measurements": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "additionalProperties": {}
            }
          },
          "intervention": {
            "type": "object",
            "properties": {},
            "additionalProperties": {}
          },
          "source_passages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "passage_id": {
                  "type": "string"
                },
                "role": {
                  "type": "string"
                }
              },
              "required": [
                "passage_id",
                "role"
              ],
              "additionalProperties": {}
            }
          },
          "validation": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string"
              }
            },
            "required": [
              "status"
            ],
            "additionalProperties": {}
          },
          "source_status": {
            "type": "string"
          },
          "meta": {
            "type": "object",
            "properties": {
              "version": {
                "type": "integer"
              },
              "valid_from_seq": {
                "type": "integer"
              },
              "valid_to_seq": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "created_at": {
                "type": "string"
              },
              "record_hash": {
                "type": "string"
              }
            },
            "required": [
              "version",
              "valid_from_seq",
              "valid_to_seq",
              "created_at",
              "record_hash"
            ],
            "additionalProperties": {}
          }
        },
        "required": [
          "record_type",
          "finding_id",
          "publication_id",
          "evidence_class"
        ],
        "additionalProperties": {},
        "description": "One claim from one source, with the source sentences that support it."
      }
    },
    "access": {
      "type": "object",
      "properties": {
        "plan_id": {
          "type": "string"
        },
        "results_withheld": {
          "type": "integer",
          "minimum": 0
        },
        "fields_withheld": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "plan_id",
        "results_withheld",
        "fields_withheld"
      ]
    },
    "usage": {
      "type": "object",
      "properties": {
        "units_charged": {
          "type": "number",
          "minimum": 0,
          "description": "Units that this request used."
        },
        "meter": {
          "type": "string",
          "enum": [
            "query",
            "live_lookups",
            "chat_messages",
            "exports"
          ],
          "description": "Meter that counted this request."
        },
        "remaining": {
          "type": [
            "number",
            "null"
          ],
          "description": "Units left in the current window. Null means no limit."
        },
        "window_resets_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "When the current window ends (ISO 8601)."
        }
      },
      "required": [
        "units_charged",
        "meter",
        "remaining",
        "window_resets_at"
      ],
      "description": "Usage of this request. REST also sends these values in RateLimit headers."
    },
    "notices": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "text"
        ]
      },
      "description": "contains_unchecked_papers marks results without checked findings. offline_snapshot marks local data. ranked_results marks a hybrid-ranked list: total_count is the length of the ranked list, not the number of documents that contain the search words (the notice text gives that number). no_checked_findings_match marks an empty findings search: it is not evidence that no evidence exists. no_registered_trials marks a trial search of one peptide that found no trial testing it. other_registry_entries marks registry entries that only measure or mention the peptide."
    },
    "included": {
      "type": "object",
      "properties": {
        "publications": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "pmid": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "pmcid": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "doi": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": "string"
              },
              "journal": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "year": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "pub_date": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "design_hint": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "PubMed publication-type tag of the paper (for example rct or review), not checked. It is the label of the journal record, not a finding. For the design, species and peptide role of the checked findings, read profile."
              },
              "status": {
                "type": "string"
              },
              "is_open_access": {
                "type": "boolean"
              },
              "license": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "oa_pdf_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "oa_landing_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "cited_by_count": {
                "type": "integer"
              },
              "first_author": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "extraction_status": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "pmid",
              "pmcid",
              "doi",
              "title",
              "journal",
              "year",
              "pub_date",
              "design_hint",
              "status",
              "is_open_access",
              "license",
              "oa_pdf_url",
              "oa_landing_url",
              "cited_by_count",
              "first_author",
              "extraction_status"
            ],
            "additionalProperties": {}
          }
        },
        "peptides": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "slug": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "id",
              "slug",
              "name"
            ]
          }
        },
        "passages": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "passage_id": {
                "type": "string"
              },
              "role": {
                "type": "string"
              },
              "section": {
                "type": "string"
              },
              "text": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Source sentence. Null when the license does not allow the text (see withheld)."
              },
              "withheld": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "publication_id": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "passage_id",
              "role",
              "section",
              "text",
              "withheld",
              "publication_id"
            ]
          }
        }
      },
      "required": [
        "publications",
        "peptides",
        "passages"
      ]
    }
  },
  "required": [
    "credit",
    "record_type",
    "query_id",
    "data_seq",
    "request",
    "total_count",
    "returned",
    "next_cursor",
    "complete",
    "result_set_hash",
    "results",
    "access",
    "usage"
  ]
}