PepBank Records API

openapi: 3.2.0
info:
  title: PepBank Records API
  version: 1.0.0
  description: 'PepBank is an open, academic-grade database of peptide research. Every finding links to the sentence in the paper that supports it, and every finding has an evidence class: **human**, **animal**, **laboratory** or **predicted**.


    The same operations are available through the hosted MCP server (`/mcp`).


    ## Authentication


    Anonymous requests work with the Visitor quotas. For your own plan and quotas, send an API key: `Authorization: Bearer pepbank_...` or `X-API-Key: pepbank_...`. Create keys on your account page. Never put a key in browser code.


    ## Pagination and completeness


    Searches return a `search_response`. `total_count` is exact. Send `next_cursor` as `cursor` to read the next page, with the same filters. Every page reads the same `data_seq`, so the set does not change while you page. `complete` is true only on the last page, and the last page carries `result_set_hash` (SHA-256 of the ordered result IDs, joined by newline).


    ## Reproducibility


    `query_id` names a normalized query at one `data_seq`. `GET /v1/queries/{query_id}` runs it again and compares the hash. `as_of_seq` reads records as they were at an earlier `data_seq`. `GET /v1/changes` is the change feed.


    ## Data layers


    1. Study results (`/v1/findings`): extracted from papers and checked by code checks and an independent model review (`auto_checked`) or by a reviewer (`human_verified`).

    2. Stored papers (`/v1/publications`): papers without study results carry the notice `contains_unchecked_papers`.

    3. Live search (`/v1/live/publications`): Europe PMC, live. Labeled `live_result_not_checked`. Never mixed with findings.


    ## Errors and limits


    Errors are RFC 9457 problem details (`application/problem+json`) with a stable `code`. Each response that counts against a quota carries `RateLimit-Policy` and `RateLimit` headers (IETF draft-ietf-httpapi-ratelimit-headers-11). A 429 response carries `Retry-After`.


    ## License


    PepBank data is CC BY 4.0. Abstract and quotation text keeps the license of its source. Cite the `data_seq` that you used.


    **Information, not medical advice.** The API never recommends a dose. Doses appear only as studied doses in findings.'
  contact:
    name: PepBank
    url: https://pepbank.io/developers
    email: info@pepbank.io
  license:
    name: API terms; data CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  x-contract-version: 0.3.0
servers:
- url: https://pepbank.io
  description: Production
security:
- {}
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Records
  description: Single records by ID, also at an earlier data_seq.
paths:
  /v1/records/{id}:
    get:
      operationId: getRecord
      summary: Get one peptide, publication, finding or trial record
      description: 'Return one full peptide, publication, finding or trial record by PEP-, PUB-, FND- or TRL- ID. A peptide slug, PMID or NCT number also works. Use this for known records or fields omitted from compact results. Use resolve_peptide instead for an unclear name, or search_publications to find papers. as_of_seq selects an earlier data_seq. Use replay_query instead to repeat a saved search.


        Meter: `query`. MCP tool: `get_record`.'
      tags:
      - Records
      parameters:
      - schema:
          type: string
          minLength: 3
          maxLength: 200
          description: Record ID. IDs start with PEP-, PUB-, FND- or TRL-. A peptide slug, a PMID or an NCT number also works.
        required: true
        description: Record ID. IDs start with PEP-, PUB-, FND- or TRL-. A peptide slug, a PMID or an NCT number also works.
        name: id
        in: path
      - schema:
          type: integer
          minimum: 0
          description: Read the data as it was at this data_seq. Use it to reproduce an earlier answer.
        required: false
        description: Read the data as it was at this data_seq. Use it to reproduce an earlier answer.
        name: as_of_seq
        in: query
      responses:
        '200':
          description: Get record
          headers:
            RateLimit:
              description: Remaining units and seconds until the window resets, for the meter of this operation.
              schema:
                type: string
                example: '"query";r=1987;t=40210'
            RateLimit-Policy:
              description: 'Quota of the meter: units (q) per window (w, seconds).'
              schema:
                type: string
                example: '"query";q=2000;w=86400'
            X-Request-Id:
              description: ID of this request. Quote it in support requests.
              schema:
                type: string
            ETag:
              description: Tag of the data (without the usage block). Send it in If-None-Match.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordResponse'
        '304':
          description: 'Not modified: the data is the same as your copy (If-None-Match).'
        '400':
          description: 'Invalid parameters, cursor or ambiguous name (code: invalid_request, invalid_cursor, ambiguous_name).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: 'The API key is not valid (code: unauthorized).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: 'Not found (code: not_found).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: 'The quota of the meter is used (code: quota_exceeded). Wait Retry-After seconds.'
          headers:
            RateLimit:
              description: Remaining units and seconds until the window resets, for the meter of this operation.
              schema:
                type: string
                example: '"query";r=1987;t=40210'
            RateLimit-Policy:
              description: 'Quota of the meter: units (q) per window (w, seconds).'
              schema:
                type: string
                example: '"query";q=2000;w=86400'
            X-Request-Id:
              description: ID of this request. Quote it in support requests.
              schema:
                type: string
            Retry-After:
              description: Seconds until the window resets.
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: 'Internal error (code: internal).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /v1/peptides/{id}:
    get:
      operationId: getPeptide
      summary: Get one peptide record
      description: 'Get one peptide record by ID (PEP-000001 or bpc-157). Same response as GET /v1/records/{id}. Use as_of_seq to read an earlier version.


        Meter: `query`.'
      tags:
      - Records
      parameters:
      - schema:
          type: string
          minLength: 3
          maxLength: 200
          description: Record ID. IDs start with PEP-, PUB-, FND- or TRL-. A peptide slug, a PMID or an NCT number also works.
        required: true
        description: Record ID. IDs start with PEP-, PUB-, FND- or TRL-. A peptide slug, a PMID or an NCT number also works.
        name: id
        in: path
      - schema:
          type: integer
          minimum: 0
          description: Read the data as it was at this data_seq. Use it to reproduce an earlier answer.
        required: false
        description: Read the data as it was at this data_seq. Use it to reproduce an earlier answer.
        name: as_of_seq
        in: query
      responses:
        '200':
          description: Get record
          headers:
            RateLimit:
              description: Remaining units and seconds until the window resets, for the meter of this operation.
              schema:
                type: string
                example: '"query";r=1987;t=40210'
            RateLimit-Policy:
              description: 'Quota of the meter: units (q) per window (w, seconds).'
              schema:
                type: string
                example: '"query";q=2000;w=86400'
            X-Request-Id:
              description: ID of this request. Quote it in support requests.
              schema:
                type: string
            ETag:
              description: Tag of the data (without the usage block). Send it in If-None-Match.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordResponse'
        '304':
          description: 'Not modified: the data is the same as your copy (If-None-Match).'
        '400':
          description: 'Invalid parameters, cursor or ambiguous name (code: invalid_request, invalid_cursor, ambiguous_name).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: 'The API key is not valid (code: unauthorized).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: 'Not found (code: not_found).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: 'The quota of the meter is used (code: quota_exceeded). Wait Retry-After seconds.'
          headers:
            RateLimit:
              description: Remaining units and seconds until the window resets, for the meter of this operation.
              schema:
                type: string
                example: '"query";r=1987;t=40210'
            RateLimit-Policy:
              description: 'Quota of the meter: units (q) per window (w, seconds).'
              schema:
                type: string
                example: '"query";q=2000;w=86400'
            X-Request-Id:
              description: ID of this request. Quote it in support requests.
              schema:
                type: string
            Retry-After:
              description: Seconds until the window resets.
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: 'Internal error (code: internal).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /v1/publications/{id}:
    get:
      operationId: getPublication
      summary: Get one publication record
      description: 'Get one publication record by ID (PUB-28408902 or a PMID). Same response as GET /v1/records/{id}. Use as_of_seq to read an earlier version.


        Meter: `query`.'
      tags:
      - Records
      parameters:
      - schema:
          type: string
          minLength: 3
          maxLength: 200
          description: Record ID. IDs start with PEP-, PUB-, FND- or TRL-. A peptide slug, a PMID or an NCT number also works.
        required: true
        description: Record ID. IDs start with PEP-, PUB-, FND- or TRL-. A peptide slug, a PMID or an NCT number also works.
        name: id
        in: path
      - schema:
          type: integer
          minimum: 0
          description: Read the data as it was at this data_seq. Use it to reproduce an earlier answer.
        required: false
        description: Read the data as it was at this data_seq. Use it to reproduce an earlier answer.
        name: as_of_seq
        in: query
      responses:
        '200':
          description: Get record
          headers:
            RateLimit:
              description: Remaining units and seconds until the window resets, for the meter of this operation.
              schema:
                type: string
                example: '"query";r=1987;t=40210'
            RateLimit-Policy:
              description: 'Quota of the meter: units (q) per window (w, seconds).'
              schema:
                type: string
                example: '"query";q=2000;w=86400'
            X-Request-Id:
              description: ID of this request. Quote it in support requests.
              schema:
                type: string
            ETag:
              description: Tag of the data (without the usage block). Send it in If-None-Match.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordResponse'
        '304':
          description: 'Not modified: the data is the same as your copy (If-None-Match).'
        '400':
          description: 'Invalid parameters, cursor or ambiguous name (code: invalid_request, invalid_cursor, ambiguous_name).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: 'The API key is not valid (code: unauthorized).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: 'Not found (code: not_found).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: 'The quota of the meter is used (code: quota_exceeded). Wait Retry-After seconds.'
          headers:
            RateLimit:
              description: Remaining units and seconds until the window resets, for the meter of this operation.
              schema:
                type: string
                example: '"query";r=1987;t=40210'
            RateLimit-Policy:
              description: 'Quota of the meter: units (q) per window (w, seconds).'
              schema:
                type: string
                example: '"query";q=2000;w=86400'
            X-Request-Id:
              description: ID of this request. Quote it in support requests.
              schema:
                type: string
            Retry-After:
              description: Seconds until the window resets.
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: 'Internal error (code: internal).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /v1/papers/{id}:
    get:
      operationId: getPaper
      summary: Get one paper record
      description: 'Get one paper record by ID (PUB-28408902 or a PMID). Same response as GET /v1/records/{id}. Use as_of_seq to read an earlier version.


        Meter: `query`.'
      tags:
      - Records
      parameters:
      - schema:
          type: string
          minLength: 3
          maxLength: 200
          description: Record ID. IDs start with PEP-, PUB-, FND- or TRL-. A peptide slug, a PMID or an NCT number also works.
        required: true
        description: Record ID. IDs start with PEP-, PUB-, FND- or TRL-. A peptide slug, a PMID or an NCT number also works.
        name: id
        in: path
      - schema:
          type: integer
          minimum: 0
          description: Read the data as it was at this data_seq. Use it to reproduce an earlier answer.
        required: false
        description: Read the data as it was at this data_seq. Use it to reproduce an earlier answer.
        name: as_of_seq
        in: query
      responses:
        '200':
          description: Get record
          headers:
            RateLimit:
              description: Remaining units and seconds until the window resets, for the meter of this operation.
              schema:
                type: string
                example: '"query";r=1987;t=40210'
            RateLimit-Policy:
              description: 'Quota of the meter: units (q) per window (w, seconds).'
              schema:
                type: string
                example: '"query";q=2000;w=86400'
            X-Request-Id:
              description: ID of this request. Quote it in support requests.
              schema:
                type: string
            ETag:
              description: Tag of the data (without the usage block). Send it in If-None-Match.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordResponse'
        '304':
          description: 'Not modified: the data is the same as your copy (If-None-Match).'
        '400':
          description: 'Invalid parameters, cursor or ambiguous name (code: invalid_request, invalid_cursor, ambiguous_name).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: 'The API key is not valid (code: unauthorized).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: 'Not found (code: not_found).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: 'The quota of the meter is used (code: quota_exceeded). Wait Retry-After seconds.'
          headers:
            RateLimit:
              description: Remaining units and seconds until the window resets, for the meter of this operation.
              schema:
                type: string
                example: '"query";r=1987;t=40210'
            RateLimit-Policy:
              description: 'Quota of the meter: units (q) per window (w, seconds).'
              schema:
                type: string
                example: '"query";q=2000;w=86400'
            X-Request-Id:
              description: ID of this request. Quote it in support requests.
              schema:
                type: string
            Retry-After:
              description: Seconds until the window resets.
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: 'Internal error (code: internal).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /v1/findings/{id}:
    get:
      operationId: getFinding
      summary: Get one finding record
      description: 'Get one finding record by ID (FND-2840890201). Same response as GET /v1/records/{id}. Use as_of_seq to read an earlier version.


        Meter: `query`.'
      tags:
      - Records
      parameters:
      - schema:
          type: string
          minLength: 3
          maxLength: 200
          description: Record ID. IDs start with PEP-, PUB-, FND- or TRL-. A peptide slug, a PMID or an NCT number also works.
        required: true
        description: Record ID. IDs start with PEP-, PUB-, FND- or TRL-. A peptide slug, a PMID or an NCT number also works.
        name: id
        in: path
      - schema:
          type: integer
          minimum: 0
          description: Read the data as it was at this data_seq. Use it to reproduce an earlier answer.
        required: false
        description: Read the data as it was at this data_seq. Use it to reproduce an earlier answer.
        name: as_of_seq
        in: query
      responses:
        '200':
          description: Get record
          headers:
            RateLimit:
              description: Remaining units and seconds until the window resets, for the meter of this operation.
              schema:
                type: string
                example: '"query";r=1987;t=40210'
            RateLimit-Policy:
              description: 'Quota of the meter: units (q) per window (w, seconds).'
              schema:
                type: string
                example: '"query";q=2000;w=86400'
            X-Request-Id:
              description: ID of this request. Quote it in support requests.
              schema:
                type: string
            ETag:
              description: Tag of the data (without the usage block). Send it in If-None-Match.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordResponse'
        '304':
          description: 'Not modified: the data is the same as your copy (If-None-Match).'
        '400':
          description: 'Invalid parameters, cursor or ambiguous name (code: invalid_request, invalid_cursor, ambiguous_name).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: 'The API key is not valid (code: unauthorized).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: 'Not found (code: not_found).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: 'The quota of the meter is used (code: quota_exceeded). Wait Retry-After seconds.'
          headers:
            RateLimit:
              description: Remaining units and seconds until the window resets, for the meter of this operation.
              schema:
                type: string
                example: '"query";r=1987;t=40210'
            RateLimit-Policy:
              description: 'Quota of the meter: units (q) per window (w, seconds).'
              schema:
                type: string
                example: '"query";q=2000;w=86400'
            X-Request-Id:
              description: ID of this request. Quote it in support requests.
              schema:
                type: string
            Retry-After:
              description: Seconds until the window resets.
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: 'Internal error (code: internal).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /v1/trials/{id}:
    get:
      operationId: getTrial
      summary: Get one trial record
      description: 'Get one trial record by ID (TRL-NCT01234567 or NCT01234567). Same response as GET /v1/records/{id}. Use as_of_seq to read an earlier version.


        Meter: `query`.'
      tags:
      - Records
      parameters:
      - schema:
          type: string
          minLength: 3
          maxLength: 200
          description: Record ID. IDs start with PEP-, PUB-, FND- or TRL-. A peptide slug, a PMID or an NCT number also works.
        required: true
        description: Record ID. IDs start with PEP-, PUB-, FND- or TRL-. A peptide slug, a PMID or an NCT number also works.
        name: id
        in: path
      - schema:
          type: integer
          minimum: 0
          description: Read the data as it was at this data_seq. Use it to reproduce an earlier answer.
        required: false
        description: Read the data as it was at this data_seq. Use it to reproduce an earlier answer.
        name: as_of_seq
        in: query
      responses:
        '200':
          description: Get record
          headers:
            RateLimit:
              description: Remaining units and seconds until the window resets, for the meter of this operation.
              schema:
                type: string
                example: '"query";r=1987;t=40210'
            RateLimit-Policy:
              description: 'Quota of the meter: units (q) per window (w, seconds).'
              schema:
                type: string
                example: '"query";q=2000;w=86400'
            X-Request-Id:
              description: ID of this request. Quote it in support requests.
              schema:
                type: string
            ETag:
              description: Tag of the data (without the usage block). Send it in If-None-Match.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordResponse'
        '304':
          description: 'Not modified: the data is the same as your copy (If-None-Match).'
        '400':
          description: 'Invalid parameters, cursor or ambiguous name (code: invalid_request, invalid_cursor, ambiguous_name).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: 'The API key is not valid (code: unauthorized).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: 'Not found (code: not_found).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: 'The quota of the meter is used (code: quota_exceeded). Wait Retry-After seconds.'
          headers:
            RateLimit:
              description: Remaining units and seconds until the window resets, for the meter of this operation.
              schema:
                type: string
                example: '"query";r=1987;t=40210'
            RateLimit-Policy:
              description: 'Quota of the meter: units (q) per window (w, seconds).'
              schema:
                type: string
                example: '"query";q=2000;w=86400'
            X-Request-Id:
              description: ID of this request. Quote it in support requests.
              schema:
                type: string
            Retry-After:
              description: Seconds until the window resets.
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: 'Internal error (code: internal).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    Problem:
      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
        type:
          type: string
          description: URI that names the problem type. Each type has a documentation page.
        title:
          type: string
          description: Short summary of the problem type.
        status:
          type: integer
          description: HTTP status code. 0 means that no HTTP response arrived (network error).
        detail:
          type: string
          description: Explanation of this occurrence.
        instance:
          type: string
          description: Path of the request that failed.
        code:
          type: string
          description: Stable machine code, for example quota_exceeded.
        request_id:
          type: string
        retry_after_s:
          type: integer
          description: Seconds to wait before a retry (quota and rate limits).
        errors:
          type: array
          items:
            type: object
            properties:
              pointer:
                type: string
                description: JSON Pointer to the field, for example /evidence_class/0.
              detail:
                type: string
            required:
            - pointer
            - detail
          description: One entry per invalid field.
      required:
      - credit
      - type
      - title
      - status
      - code
      additionalProperties: {}
      description: RFC 9457 problem details.
    RecordResponse:
      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:
          - record_response
        entity_type:
          type: string
          enum:
          - peptide
          - publication
          - finding
          - trial
        id:
          type: string
        data_seq:
          type: integer
        as_of_seq:
          type:
          - integer
          - 'null'
        record:
          type: object
          properties:
            record_type:
              type: string
          required:
          - record_type
          additionalProperties: {}
        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.
      required:
      - credit
      - record_type
      - entity_type
      - id
      - data_seq
      - as_of_seq
      - record
      - usage
      description: One record at the current data_seq or at as_of_seq.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key (pepbank_...)
      description: 'API key from your account page, sent as Authorization: Bearer pepbank_...'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: The same API key in the X-API-Key header.
externalDocs:
  description: Developer guide
  url: https://pepbank.io/developers