API Evangelist enhancements for the Calico API (projectcalico.org/v3)

# authorship: generated by API Evangelist tooling. Stamped 2026-08-18
# on the file's own generator header (roadmap#64). An unmarked file is
# NOT assumed to be ours -- absence of evidence was never stamped.
x-method: generated
overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Calico API (projectcalico.org/v3)
  version: 1.0.0
extends: openapi/tigera-calico-api-openapi-original.json
x-generated: '2026-08-05'
x-method: generated
x-source: >-
  Enhancements derived from this repo's artifacts. The harvested Swagger 2.0 document at
  https://docs.tigera.io/json/calico-api-swagger.json is never mutated; everything API Evangelist
  adds lives here as Overlay 1.0.0 actions.
actions:
- target: $.info
  update:
    title: Calico API (projectcalico.org/v3)
    description: >-
      The Calico aggregated Kubernetes API server, serving 27 custom resources for network
      policy, tiered policy, network sets, BGP, IPAM, host endpoints, observability, threat
      feeds and cluster management. Published by Tigera as a Swagger 2.0 document and rendered
      at https://docs.tigera.io/calico-cloud/reference/rest-api-reference. The upstream document
      carries the generic generated title "Generic API Server" and version "unversioned"; this
      overlay names it.
    version: projectcalico.org/v3
    contact:
      name: Tigera
      url: https://www.tigera.io/
    x-apievangelist-provider: tigera
    x-apievangelist-aid: tigera:calico-api
    x-apievangelist-artifacts:
      authentication: authentication/tigera-authentication.yml
      conventions: conventions/tigera-conventions.yml
      errors: errors/tigera-problem-types.yml
      data_model: data-model/tigera-data-model.yml
      conformance: conformance/tigera-conformance.yml
      lifecycle: lifecycle/tigera-lifecycle.yml
      skills: skills/_index.yml
- target: $
  update:
    host: kubernetes.default.svc
    basePath: /
    schemes:
    - https
    x-apievangelist-host-note: >-
      The upstream document declares no host, basePath or schemes because it is generated by the
      aggregated API server itself and served relative to whatever cluster it runs in.
      kubernetes.default.svc is the canonical in-cluster address; callers outside the cluster
      substitute their own kube-apiserver endpoint.
- target: $
  update:
    securityDefinitions:
      x-apievangelist-KubernetesBearerToken:
        type: apiKey
        name: Authorization
        in: header
        description: >-
          ADDED BY API EVANGELIST — not asserted by Tigera. The upstream document declares no
          securityDefinitions at all. In practice the fronting kube-apiserver authenticates the
          caller with a bearer token (ServiceAccount or OIDC) sent as
          "Authorization: Bearer <token>", or with a TLS client certificate. Recorded here so
          spec-driven tooling has a signal; see authentication/tigera-authentication.yml for the
          full profile, including the client-certificate and etcdv3 paths this apiKey shape
          cannot express.
- target: $
  update:
    x-apievangelist-contract-gaps:
      security_definitions: 0
      four_xx_responses_declared: 0
      five_xx_responses_declared: 0
      note: >-
        Across 261 operations the upstream document declares only 200/201/202. The
        meta/v1.Status error schema IS present in definitions but is never referenced from a
        failure response, so generated clients and agents see no failure modes. Adding
        400/401/403/404/409/422/429/500 responses that $ref the existing
        io.k8s.apimachinery.pkg.apis.meta.v1.Status definition would close this with no new
        schema work. Derived failure contract: errors/tigera-problem-types.yml.
- target: $
  update:
    x-apievangelist-agent-notes:
      idempotency: >-
        Not an Idempotency-Key header. Idempotency comes from server-side apply (PATCH with
        application/apply-patch+yaml plus a stable fieldManager), full replace (PUT), and
        resourceVersion preconditions that turn a lost update into a 409 instead of silent data
        loss.
      dry_run: >-
        Every one of the 139 write operations accepts dryRun=All. An agent should validate with
        dryRun before any write.
      pagination: limit + continue cursor; follow metadata.continue until empty.
      high_blast_radius_operations: >-
        The 31 deleteProjectcalicoOrgV3Collection* operations delete every object matching a
        selector. These should require human confirmation in any agentic deployment.