API Evangelist enhancements for the SmartLead API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the SmartLead API
  version: 1.0.0
extends: openapi/smartlead-ai-openapi.yml
x-provenance:
  generated: '2026-08-13'
  method: generated
  source: >-
    Derived from artifacts in this repository. Applies API Evangelist's findings to the
    provider-published OpenAPI without mutating it.
  base_spec_source: https://api.smartlead.ai/api-reference/openapi.yaml
actions:
- target: $.info
  description: Record the provenance of the harvested contract and the API Evangelist profile.
  update:
    x-apievangelist-profile: https://apis.io/provider/smartlead-ai
    x-apis-json: https://raw.githubusercontent.com/api-evangelist/smartlead-ai/refs/heads/main/apis.yml
    x-spec-source: https://api.smartlead.ai/api-reference/openapi.yaml
    x-spec-harvested: '2026-08-13'
- target: $.info
  description: >-
    Surface the runtime semantics that are documented in prose but absent from the contract.
  update:
    x-rate-limits: rate-limits/smartlead-ai-rate-limits.yml
    x-error-catalog: errors/smartlead-ai-problem-types.yml
    x-conventions: conventions/smartlead-ai-conventions.yml
    x-lifecycle: lifecycle/smartlead-ai-lifecycle.yml
    x-webhooks-catalog: asyncapi/smartlead-ai-webhooks.yml
    x-data-model: data-model/smartlead-ai-data-model.yml
- target: $.info
  description: Record the agent-facing surfaces SmartLead publishes.
  update:
    x-agent-card: https://api.smartlead.ai/.well-known/agent-card.json
    x-agent-skill: https://api.smartlead.ai/.well-known/agent-skills/smartlead/skill.md
    x-mcp-server: https://api.smartlead.ai/mcp
    x-mcp-scope: documentation-only — does not execute REST operations
    x-llms-txt: https://api.smartlead.ai/llms.txt
- target: $.components.securitySchemes.ApiKeyAuth
  description: >-
    Flag the credential-in-URL exposure and the undocumented request-body transport.
  update:
    x-credential-in-url: true
    x-credential-risk: >-
      The API key travels in the query string on every request and is therefore logged by proxies,
      CDNs and web servers. No header-based alternative is documented.
    x-alternate-transport: >-
      The auth docs also permit an api_key field in the JSON request body on POST/PATCH; that
      transport is not modelled in this specification.
    x-scopes: none — account-wide bearer credential with no least-privilege model
- target: $.servers[1]
  description: >-
    The advertised staging server does not resolve; mark it so a consumer does not target a dead
    host for testing.
  update:
    x-reachable: false
    x-probed: '2026-08-13'
    x-note: staging.smartlead.ai did not resolve on probe (no HTTP response).
- target: $.paths['/v1/campaigns/{campaign_id}/leads'].post
  description: Record the published bulk-import ceiling, which the schema does not express.
  update:
    x-max-batch-size: 400
    x-max-batch-unit: leads per request
    x-duplicate-behavior: >-
      Leads already present in the campaign are not re-sent; they are returned in the response's
      skipped_leads array (409 semantics documented in the error guide).
- target: $.paths..responses['429']
  description: Attach the documented rate-limit signalling to the throttled response.
  update:
    x-rate-limit-headers: [X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After]
    x-error-code: RATE_LIMIT_EXCEEDED
    x-retry: exponential backoff with jitter; honor Retry-After