API Evangelist enhancements for the Sarj.ai Developer API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Sarj.ai Developer API
  version: 1.0.0
extends: openapi/_original/sarj-ai-developer-api-developer-openapi.json
x-provenance:
  generated: '2026-09-11'
  method: generated
  source: openapi/_original/sarj-ai-developer-api-developer-openapi.json
  note: >-
    Captures API Evangelist observations as an Overlay so the harvested spec is never mutated. Every statement here is
    grounded in a probed URL or in the spec itself.
actions:
  - target: $.info
    update:
      x-apievangelist-slug: sarj-ai-developer-api
      x-apievangelist-reviewed: '2026-09-11'
      x-apievangelist-surface: public-developer-api
      x-apievangelist-note: >-
        The documented public contract: 7 operations as of 2026-09-11, up from 3 on 2026-08-09 with no
        changelog and no info.version change. A 231-operation platform spec is served unauthenticated at
        https://platform-api.sarj.ai/openapi.json and is captured separately as
        openapi/_original/sarj-ai-developer-api-voice-platform-openapi.json.
  - target: $.info
    update:
      x-agent-surfaces:
        mcp: https://platform-api.sarj.ai/api/v1/mcp
        agent_card: https://platform-docs.sarj.ai/.well-known/agent-card.json
        agent_skill: https://platform-docs.sarj.ai/.well-known/agent-skills/sarj/skill.md
        agent_skills_index: https://platform-docs.sarj.ai/.well-known/agent-skills/index.json
        mcp_docs_server_card: https://platform-docs.sarj.ai/.well-known/mcp/server-card.json
        llms_txt: https://platform-docs.sarj.ai/llms.txt
  - target: $.paths['/calls'].post
    update:
      x-apievangelist-idempotency:
        supported: false
        note: >-
          No Idempotency-Key is accepted. This operation places a real, billable phone call, so a retry after a
          timeout dials the recipient a second time. Callers must deduplicate before sending.
      x-agentic-access:
        action-class: acting
        consequence: physical
        note: >-
          Raised above the pipeline's default classification: this operation causes a phone to ring at a real
          person's number and incurs telephony cost. Treat as an irreversible external side effect.
  - target: $.paths['/calls'].post
    update:
      x-apievangelist-mcp-tool: createCall
  - target: $.paths['/calls/{call_id}'].get
    update:
      x-apievangelist-mcp-tool: getCall
      x-apievangelist-note: >-
        recording_url is a signed, time-limited URL; re-fetch this operation for a fresh one rather than storing it.
        report is null until roughly two minutes after completion and may never appear for calls that did not
        complete.
  - target: $.components.schemas.ErrorResponse
    update:
      x-apievangelist-error-format:
        rfc9457: false
        envelope: '{"error": {"type", "message"}, "meta": {"request_id"}}'
        discriminator: error.type
        types: 17
        note: >-
          Typed, discriminated and machine-branchable, but not application/problem+json. See
          errors/sarj-ai-developer-api-problem-types.yml.
  - target: $.paths['/calls'].post
    update:
      x-apievangelist-reversibility:
        reversible: conditional
        reversal_operation: cancelScheduledCall
        condition: only when created with scheduled_at and still in status 'scheduled'
        window: >-
          scheduled_at must be at least 10 minutes ahead and within 30 days, so the cancellation window runs
          from booking until the call is released for dialing.
        window_stated_by_provider: true
        note: >-
          Without scheduled_at the call dials immediately and there is no undo. An agent that wants a way
          back must deliberately book the call rather than place it.
  - target: $.paths['/calls/{call_id}/cancel'].post
    update:
      x-apievangelist-note: >-
        The provider's published Agent Skill documents this as DELETE /calls/{call_id}. That path and method
        do not exist in this specification. Recorded in skills/_index.yml as a high-severity defect.
      x-agentic-access:
        action-class: acting
        consequence: write
        reversal-of: createCall
        escalation:
          human-in-the-loop: false
          rationale: >-
            Stopping an unwanted call should not require approval. This is the provider's own "per-person
            stop-calling lever" — cancelling a pending retry ends the whole retry chain.
  - target: $.paths['/calls/{call_id}/reschedule'].post
    update:
      x-apievangelist-note: >-
        The provider's published Agent Skill documents this as PATCH /calls/{call_id}. That path and method
        do not exist in this specification.
  - target: $.paths['/schedule-configs'].post
    update:
      x-apievangelist-reversibility:
        reversible: false
        provider_acknowledged: true
        note: >-
          "This endpoint is create-only today — there is no way to fetch, list, update, or disable a config
          after creation." A retry policy created in error governs up to 10 re-dials of a real person and
          cannot be turned off through the API.
      x-agentic-access:
        escalation:
          human-in-the-loop: required
  - target: $.paths['/calls/{call_id}/recording'].get
    update:
      x-apievangelist-note: >-
        302 to a freshly minted short-lived download URL. The call-scoped X-Sarj-Recording-Token may also be
        passed as a `t` query parameter; the specification itself advises the header, because the query form
        puts a credential in a URL that will be logged.
  - target: $.components.schemas.PublicCallDetail
    update:
      x-apievangelist-deprecation:
        field: recording_url
        replacement: permanent_recording_url
        machine_readable: false
        note: >-
          Deprecated in prose only. OpenAPI 3.1 supports `deprecated: true` on a schema property and this
          field does not carry it, so no tooling will flag it. Its expiry (24 hours, or 7 days pre-rollout)
          depends on a deployment flag the caller cannot observe.
  - target: $.info
    update:
      x-apievangelist-runtime-gaps:
        idempotency: none
        rate_limit_headers: none
        published_rate_limits: 0
        published_plans: 0
        public_status_page: false
        changelog: false
        note: >-
          Recorded so the gaps travel with the contract: see conventions/, rate-limits/, plans/ and
          lifecycle/ for the evidence behind each.