API Evangelist enhancements for the Benchling v3 API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Benchling v3 API
  version: 1.0.0
extends: ../openapi/benchling-v3-openapi.yaml
x-provenance:
  generated: '2026-08-15'
  method: generated
  source: >-
    Generated by the API Evangelist enrichment pipeline. Captures the facts this
    repo established about the Benchling v3 API that the published spec leaves
    implicit — the real tenant-templated server, the external documentation, the
    contact and licence, the error format, the rate-limit signalling, and the
    absence of an idempotency key. The original spec at
    openapi/benchling-v3-openapi.yaml is never mutated.
actions:
  - target: $.info
    description: >-
      The published spec carries only a title, version and licence. Add the
      description, contact and terms Benchling publishes elsewhere.
    update:
      description: >-
        Benchling's unified v3 REST API — 805 paths and 874 operations spanning
        the electronic lab notebook, registry, inventory, assay results and
        workflow execution. Errors are RFC 9457 problem details
        (application/problem+json). Every operation is tagged with a rate-limit
        tier (x-bnch-rate-limit-tier 1-5). Beta operations on this same base
        path are gated behind the EARLY-ACCESS request header.
      contact:
        name: Benchling Support
        email: support@benchling.com
        url: https://docs.benchling.com/docs/developer-platform-overview
      termsOfService: https://www.benchling.com/agreements-and-terms
  - target: $.servers
    description: >-
      The published spec declares only the relative path "/api/v3", which is not
      resolvable on its own. Benchling is tenant-scoped: every customer has its
      own subdomain, documented at
      https://docs.benchling.com/docs/authentication.
    update:
      - url: https://{tenant}.benchling.com/api/v3
        description: Benchling tenant API host
        variables:
          tenant:
            default: benchling
            description: >-
              Your Benchling tenant subdomain — e.g. yourcompany for
              yourcompany.benchling.com. Enterprise customers must use their own
              company URL.
  - target: $
    description: Add external documentation, absent from the published spec.
    update:
      externalDocs:
        description: Benchling Developer Platform documentation
        url: https://docs.benchling.com/docs/developer-platform-overview
  - target: $.components.schemas.GeneralError
    description: >-
      Name the standard this schema implements so tooling can recognise it as
      RFC 9457 problem details rather than a bespoke envelope.
    update:
      title: Problem Details (RFC 9457)
      description: >-
        RFC 9457 problem detail object, returned as application/problem+json.
        Members type, title, detail, status and instance are all required. See
        errors/benchling-problem-types.yml.
      externalDocs:
        description: RFC 9457 — Problem Details for HTTP APIs
        url: https://www.rfc-editor.org/rfc/rfc9457
  - target: $.components.schemas.InternalServerError
    description: Document the errorId member, which is the value to quote to Benchling support.
    update:
      description: >-
        RFC 9457 problem detail for a 500, extended with an `errorId` member
        that correlates the failure with Benchling's internal logs. Quote it
        when contacting support@benchling.com.
  - target: $.components.securitySchemes.oAuth
    description: >-
      Record that the empty scopes object is deliberate — Benchling has no API
      scopes and authorizes by organization/team/project membership.
    update:
      description: >-
        OAuth 2.0 client credentials flow for Benchling Apps (service
        principals). NOTE: Benchling defines NO OAuth scopes. An app's
        authority is whatever an administrator has granted it by adding it to
        organizations, teams and projects — the same model applied to users. See
        scopes/benchling-scopes.yml.
  - target: $.components.securitySchemes.basicApiKeyAuth
    description: Spell out the empty-password convention that trips up first-time callers.
    update:
      description: >-
        HTTP Basic with the user API key as the USERNAME and an EMPTY password
        (note the trailing colon in `curl -u KEY:`). Requests that fail
        authentication return 401. Keys are rotated from Profile settings.
  - target: $.components.parameters.pageSize
    description: Cross-reference the documented pagination contract.
    update:
      description: >-
        Number of results to return. Defaults to 50, maximum 100. Every list
        endpoint is paginated; continue with the opaque nextToken cursor. See
        conventions/benchling-conventions.yml.
  - target: $.components.responses.TooManyRequests
    description: >-
      Attach the runtime rate-limit signalling an agent needs, which the spec
      does not express.
    update:
      description: >-
        Too Many Requests. Returned when a request-rate limit (60/30s per tenant
        across user keys, 300/30s per app key, 1000/30s per tenant across apps)
        or the dynamic hourly throughput limit is exceeded. Responses carry
        x-rate-limit-limit, x-rate-limit-remaining and x-rate-limit-reset; there
        is NO Retry-After header. Requests refused with 429 are not queued for
        resubmission — retry with exponential backoff plus jitter, capped around
        15 seconds. See rate-limits/benchling-rate-limits.yml.
  - target: $.paths.*.*.parameters
    description: >-
      No idempotency key exists anywhere in this API. Recorded once, as an
      overlay-level fact, rather than injected into 874 operations — a retried
      POST can create a duplicate object.
    update: []
x-notes:
  idempotency: >-
    NOT SUPPORTED. Benchling publishes no Idempotency-Key header and none
    appears in the spec. The documented mitigations are the Batch/Bulk write
    families and 429 backoff.
  webhooks: >-
    The spec's top-level `webhooks` object declares 14 v3.* events. A second,
    separate v2.* event stream is delivered through Amazon EventBridge and is
    not in the OpenAPI at all — see asyncapi/benchling-webhooks.yml.
  rate_limit_tiers: >-
    x-bnch-rate-limit-tier assigns every operation a cost class 1-5 (observed
    distribution: tier 2 = 130, tier 3 = 132, tier 4 = 427, tier 5 = 184). The
    per-tier numbers are not published.