{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/pepbank-io/json-schema/pepbank-io-publication-search-response-schema.json",
  "title": "PublicationSearchResponse",
  "description": "Stored publications (layers 1 and 2). Papers without checked findings carry the notice contains_unchecked_papers. design_hint is the PubMed publication-type tag, not checked; profile comes from the checked findings.",
  "x-generated": "2026-11-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/pepbank-io-openapi.json#/components/schemas/PublicationSearchResponse",
  "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": [
              "publication"
            ]
          },
          "publication_id": {
            "type": "string"
          },
          "ids": {
            "type": "object",
            "properties": {
              "pmid": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "pmcid": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "doi": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "additionalProperties": {}
          },
          "title": {
            "type": "string"
          },
          "journal": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "processing": {
            "type": "object",
            "properties": {
              "extraction_status": {
                "type": "string"
              }
            },
            "required": [
              "extraction_status"
            ],
            "additionalProperties": {}
          },
          "abstract": {
            "type": [
              "string",
              "null"
            ],
            "description": "Abstract text. Present only when the article license allows reuse."
          },
          "abstract_withheld_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "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",
          "publication_id",
          "title"
        ],
        "additionalProperties": {},
        "description": "Publication metadata. Abstract text only when the license allows 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"
              },
              "finding_count": {
                "type": "integer"
              },
              "abstract_available": {
                "type": "boolean"
              },
              "profile": {
                "type": "object",
                "properties": {
                  "scope": {
                    "type": "string",
                    "enum": [
                      "peptide",
                      "all"
                    ],
                    "description": "\"peptide\": the counts are the findings of the peptide in the filter. \"all\": the findings of every peptide in the paper. Do not word an \"all\" profile as being about one peptide."
                  },
                  "findings": {
                    "type": "object",
                    "properties": {
                      "administered": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Checked findings from a study that gave the peptide."
                      },
                      "endogenous_level": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Checked findings that measure the body's own peptide. Not evidence about taking it."
                      },
                      "other": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Checked findings where the peptide was a tool, a carrier or the subject of a method. Not evidence about the peptide alone."
                      },
                      "total": {
                        "type": "integer",
                        "minimum": 0
                      }
                    },
                    "required": [
                      "administered",
                      "endogenous_level",
                      "other",
                      "total"
                    ],
                    "description": "Checked findings of the paper by the role of the peptide."
                  },
                  "by_class": {
                    "type": "object",
                    "properties": {
                      "human": {
                        "type": "integer"
                      },
                      "animal": {
                        "type": "integer"
                      },
                      "laboratory": {
                        "type": "integer"
                      },
                      "predicted": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "human",
                      "animal",
                      "laboratory",
                      "predicted"
                    ],
                    "description": "Administered findings by evidence class."
                  },
                  "primary_role": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "administered",
                      "endogenous_level",
                      "other",
                      null
                    ],
                    "description": "administered when any finding gave the peptide, else endogenous_level, else other. Null without checked findings."
                  },
                  "top_class": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "human",
                      "animal",
                      "laboratory",
                      "predicted",
                      null
                    ],
                    "description": "Strongest class among the administered findings."
                  },
                  "top_design": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Strongest design among the administered findings of the top class."
                  },
                  "designs": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Distinct designs of the administered findings, strongest first (at most 3)."
                  },
                  "species": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Species named by the administered findings of the top class (at most 3)."
                  },
                  "max_sample_size": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "top_analysis_role": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Best analysis role (primary, secondary, exploratory, not_stated) among the administered findings of the top class and the top design tier. Part of the ranking rule key_findings_v0.4."
                  },
                  "endogenous_designs": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "pub_types": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "PubMed publication-type tags of the paper. Tags, not findings: never present one as a finding about people."
                  },
                  "peptides": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "peptide_id": {
                          "type": "string"
                        },
                        "slug": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "name": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "role": {
                          "type": "string",
                          "enum": [
                            "administered",
                            "endogenous_level",
                            "other"
                          ],
                          "description": "administered when any checked finding gave this peptide, else endogenous_level, else other."
                        },
                        "findings": {
                          "type": "object",
                          "properties": {
                            "administered": {
                              "type": "integer",
                              "minimum": 0,
                              "description": "Checked findings from a study that gave the peptide."
                            },
                            "endogenous_level": {
                              "type": "integer",
                              "minimum": 0,
                              "description": "Checked findings that measure the body's own peptide. Not evidence about taking it."
                            },
                            "other": {
                              "type": "integer",
                              "minimum": 0,
                              "description": "Checked findings where the peptide was a tool, a carrier or the subject of a method. Not evidence about the peptide alone."
                            },
                            "total": {
                              "type": "integer",
                              "minimum": 0
                            }
                          },
                          "required": [
                            "administered",
                            "endogenous_level",
                            "other",
                            "total"
                          ]
                        },
                        "top_class": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "enum": [
                            "human",
                            "animal",
                            "laboratory",
                            "predicted",
                            null
                          ],
                          "description": "Strongest class among the administered findings of this peptide."
                        },
                        "top_design": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Strongest design among those findings."
                        },
                        "species": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Species of those findings (at most 3)."
                        }
                      },
                      "required": [
                        "peptide_id",
                        "slug",
                        "name",
                        "role",
                        "findings",
                        "top_class",
                        "top_design",
                        "species"
                      ]
                    },
                    "description": "The role of every peptide that has checked findings in the paper."
                  }
                },
                "required": [
                  "scope",
                  "findings",
                  "by_class",
                  "primary_role",
                  "top_class",
                  "top_design",
                  "designs",
                  "species",
                  "max_sample_size",
                  "endogenous_designs",
                  "pub_types"
                ],
                "description": "From the checked findings of the paper: classes, designs, species and the role of each peptide. design_hint is the PubMed tag, not checked."
              }
            },
            "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",
              "finding_count",
              "abstract_available"
            ],
            "additionalProperties": {}
          }
        }
      },
      "required": [
        "publications"
      ]
    }
  },
  "required": [
    "credit",
    "record_type",
    "query_id",
    "data_seq",
    "request",
    "total_count",
    "returned",
    "next_cursor",
    "complete",
    "result_set_hash",
    "results",
    "access",
    "usage"
  ]
}