{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/pepbank-io/json-schema/pepbank-io-peptide-search-response-schema.json",
  "title": "PeptideSearchResponse",
  "description": "Peptide search results (cards).",
  "x-generated": "2026-11-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/pepbank-io-openapi.json#/components/schemas/PeptideSearchResponse",
  "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": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "featured": {
            "type": "boolean"
          },
          "one_liner": {
            "type": [
              "string",
              "null"
            ]
          },
          "sequence": {
            "type": [
              "string",
              "null"
            ]
          },
          "length": {
            "type": [
              "integer",
              "null"
            ]
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "regulatory_status": {
            "type": [
              "string",
              "null"
            ],
            "description": "A sort key, never an answer: it does not say where. Quote approval instead."
          },
          "approval": {
            "type": "string",
            "description": "Approval status in words, with the places: for example \"Approved in the US and EU (Ozempic, 2017)\". Quote it as written; never write only the word approved."
          },
          "highest_phase": {
            "type": [
              "string",
              "null"
            ]
          },
          "stats": {
            "type": "object",
            "properties": {
              "publications": {
                "type": "integer"
              },
              "publications_checked": {
                "type": "integer",
                "description": "In-scope linked papers with extraction_status extracted, with or without findings."
              },
              "findings": {
                "type": "integer"
              },
              "by_class": {
                "type": "object",
                "properties": {
                  "human": {
                    "type": "object",
                    "properties": {
                      "publications": {
                        "type": "integer"
                      },
                      "findings": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "publications",
                      "findings"
                    ]
                  },
                  "animal": {
                    "type": "object",
                    "properties": {
                      "publications": {
                        "type": "integer"
                      },
                      "findings": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "publications",
                      "findings"
                    ]
                  },
                  "laboratory": {
                    "type": "object",
                    "properties": {
                      "publications": {
                        "type": "integer"
                      },
                      "findings": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "publications",
                      "findings"
                    ]
                  },
                  "predicted": {
                    "type": "object",
                    "properties": {
                      "publications": {
                        "type": "integer"
                      },
                      "findings": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "publications",
                      "findings"
                    ]
                  }
                },
                "required": [
                  "human",
                  "animal",
                  "laboratory",
                  "predicted"
                ]
              },
              "trials": {
                "type": "integer",
                "description": "Registered trials that test the peptide (role tests: it is among the interventions). Registry entries that only measure or mention it are in trials_other."
              },
              "trials_active": {
                "type": "integer",
                "description": "Trials that test the peptide and are recruiting, not yet recruiting, active or enrolling by invitation."
              },
              "trials_other": {
                "type": "integer",
                "description": "Registry entries that name the peptide but do not test it: it is only a measured level or an eligibility term (measures), or named in the text (mentions). They are not trials of the peptide. Say \"<n> more trial records measure or name it but do not test it\"."
              },
              "latest_publication": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "retracted_publications": {
                "type": "integer"
              },
              "out_of_scope": {
                "type": "integer",
                "description": "Stored papers that are out of scope for this peptide by a scope policy (for example oxytocin_childbirth_v1). PepBank does not check them, and they are not part of any \"not checked yet\" count. publications still counts every stored paper."
              },
              "evidence_level": {
                "type": "string",
                "enum": [
                  "human_rct",
                  "human_other",
                  "animal",
                  "laboratory",
                  "predicted",
                  "none"
                ],
                "description": "From checked findings of studies that gave the peptide only: human_rct, human_other, animal, laboratory, predicted or none. A registered trial, a trial phase or an approval never raises it."
              },
              "registry_level": {
                "type": "string",
                "enum": [
                  "approved",
                  "phase_4",
                  "phase_3",
                  "phase_2",
                  "phase_1",
                  "registered",
                  "none"
                ],
                "description": "From the registered trials that test the peptide and the curated development phase: approved (somewhere, for some use), phase_4, phase_3, phase_2, phase_1, registered or none. It says nothing about results. Never show approved as a bare Approved: use the regulatory block."
              },
              "human_rct_findings": {
                "type": "integer",
                "description": "Checked findings from randomized controlled trials in people, from studies that gave the peptide. Basis of the evidence level human_rct."
              },
              "trials_top_phase": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "phase_4",
                  "phase_3",
                  "phase_2",
                  "phase_1",
                  null
                ],
                "description": "Highest phase among the registered trials that test the peptide. Null when none has a phase. Early phase 1 counts as phase_1."
              },
              "endogenous_findings": {
                "type": "integer",
                "description": "Checked findings that measure the body's own peptide. They are not counted in findings or by_class."
              }
            },
            "required": [
              "publications",
              "findings",
              "by_class",
              "trials",
              "trials_active",
              "latest_publication",
              "retracted_publications",
              "evidence_level"
            ],
            "additionalProperties": {}
          }
        },
        "required": [
          "id",
          "slug",
          "name",
          "kind",
          "category",
          "featured",
          "one_liner",
          "sequence",
          "length",
          "aliases",
          "regulatory_status",
          "highest_phase",
          "stats"
        ],
        "additionalProperties": {},
        "description": "Peptide card: identity plus evidence counts."
      }
    },
    "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": {}
    }
  },
  "required": [
    "credit",
    "record_type",
    "query_id",
    "data_seq",
    "request",
    "total_count",
    "returned",
    "next_cursor",
    "complete",
    "result_set_hash",
    "results",
    "access",
    "usage"
  ]
}