PepBank Account API

openapi: 3.2.0
info:
  title: PepBank Account 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: Account
  description: Plan, usage and source freshness.
paths:
  /v1/freshness:
    get:
      operationId: getFreshness
      summary: When each source was last read
      description: 'Return source import and extraction times from stored study results. Use this to inspect data freshness. Use get_changes instead for record events, or get_my_usage for caller quotas. lag_hours measures time since success, not upstream backlog. source_latest_known is not reported yet and remains null.


        Free: not metered. MCP tool: `get_freshness`.'
      tags:
      - Account
      responses:
        '200':
          description: Get freshness
          headers:
            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/FreshnessReport'
        '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'
        '500':
          description: 'Internal error (code: internal).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /v1/me:
    get:
      operationId: getMe
      summary: Your plan, grants and usage
      description: 'Return the caller''s plan, grants, quotas and usage in the current windows. Use this to inspect access limits and remaining allowances. Use get_freshness instead for source import times, or get_changes for record updates. This tool reports account access, not evidence coverage.


        Free: not metered. MCP tool: `get_my_usage`.'
      tags:
      - Account
      responses:
        '200':
          description: Get my usage
          headers:
            X-Request-Id:
              description: ID of this request. Quote it in support requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountUsage'
        '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'
        '500':
          description: 'Internal error (code: internal).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /v1/plans:
    get:
      operationId: listPlans
      summary: Plans, grants and quotas
      description: 'List the plans with their grants and quotas. Draft plans are listed with available: false.


        Free: not metered.'
      tags:
      - Account
      responses:
        '200':
          description: List plans
          headers:
            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/PlanList'
        '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'
        '500':
          description: 'Internal error (code: internal).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    PlanList:
      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:
          - plan_list
        pricing_enabled:
          type: boolean
        plans:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              audience:
                type: string
              status:
                type: string
              available:
                type: boolean
              price:
                type: object
                properties: {}
                additionalProperties: {}
              highlights:
                type: array
                items:
                  type: string
              grants:
                type: object
                properties: {}
                additionalProperties: {}
              quotas:
                type: array
                items:
                  type: object
                  properties:
                    meter:
                      type: string
                    limit:
                      type:
                      - number
                      - 'null'
                  required:
                  - meter
                  - limit
                  additionalProperties: {}
            required:
            - id
            - name
            - audience
            - status
            - available
            - price
            - highlights
            - grants
            - quotas
            additionalProperties: {}
      required:
      - credit
      - record_type
      - pricing_enabled
      - plans
      description: 'Plans, grants and quotas. Draft plans show available: false.'
    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.
    FreshnessReport:
      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:
          - freshness_report
        generated_at:
          type: string
        data_seq:
          type: integer
        sources:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              last_success_at:
                type: string
              watermark:
                type: string
              source_latest_known:
                type:
                - string
                - 'null'
                description: Upstream latest time is not reported yet. This field is null.
              lag_hours:
                type: number
                description: Elapsed hours since the last recorded success, not upstream backlog. 9999 means no recorded success.
              state:
                type: string
                enum:
                - fresh
                - behind
                - failing
              open_failed_items:
                type: integer
              label:
                type: string
              records:
                type:
                - integer
                - 'null'
            required:
            - source
            - last_success_at
            - watermark
            - lag_hours
            - state
            additionalProperties: {}
      required:
      - credit
      - record_type
      - generated_at
      - data_seq
      - sources
      description: When sources last succeeded. Extraction uses timestamps from stored study results. lag_hours measures elapsed time, not upstream backlog.
    AccountUsage:
      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:
          - account_usage
        account:
          type: object
          properties:
            account_key:
              type: string
            account_id:
              type:
              - string
              - 'null'
            kind:
              type: string
          required:
          - account_key
          - account_id
          - kind
        plan:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
          required:
          - id
          - name
        entitlement:
          type: object
          properties: {}
          additionalProperties: {}
        usage:
          type: array
          items:
            type: object
            properties:
              meter:
                type: string
              limit:
                type:
                - number
                - 'null'
              used:
                type:
                - number
                - 'null'
              remaining:
                type:
                - number
                - 'null'
              window:
                type: string
              window_resets_at:
                type: string
            required:
            - meter
            - limit
            - used
            - remaining
            - window
            - window_resets_at
      required:
      - credit
      - record_type
      - account
      - plan
      - entitlement
      - usage
      description: The caller's account, plan, grants and usage in the current windows.
  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