• build-mule-integration

  Phase 2 — uses

  api-reference.md

  's Authentication, Rate Limits, Use Cases, and Entity Reference sections to generate HTTP Request configs and DataWeave transforms.
• The user, post-merge —

  <apiName>.yaml

  is a real OpenAPI 3.0 spec they can publish to Exchange or feed into other tooling.

1. Credential collection — when

   config.properties

   does not exist or lacks required keys, the skill creates it with placeholders, asks the user to fill it in, and waits. Mandatory — do NOT skip validation, write a placeholder report, or proceed without credentials.
2. Entity IDs — when an operation requires references to existing entities, the skill asks the user to provide them.
3. Destructive operation confirmation — before executing DELETE or destructive PUT, the skill warns the user about consequences and asks for confirmation.
4. Unresolvable failures — after the validation loop completes, if any operations failed, the skill asks the user how to proceed (retry / keep / remove / cancel).

1. NEVER read, display, echo, log, or reason about credential values from

   config.properties

   .
2. To verify a credential key exists, use

   grep -c '^KEY_NAME=' config.properties

   — this returns a count (0 or 1), not the value.
3. To inject credentials into

   curl

   commands, use inline shell substitution:

   $(grep '^KEY_NAME=' config.properties | cut -d'=' -f2-)

   . The value flows through the shell but never enters conversation context.
4. If a curl command's output accidentally contains credentials (e.g., in error messages), do NOT repeat that output. Summarize the result without the sensitive content.

$ARGUMENTS

1. apiName

   — the SaaS platform / API name in kebab-case (e.g.,

   canva-lms

   ,

   jira

   ,

   coda

   ). This becomes the subfolder under

   connectivity-schema/

   and the OpenAPI filename.

2. useCases

   — one or more concrete operations the integration needs. Examples:
   • "Get the newest courses and notify on new ones"
   • "Retrieve a Jira ticket and update its status"

3. Project Folder

   (optional) — directory where output files are written. Defaults to

   <workspaceRoot>/connectivity-schema/<apiName>/

   . Resolve

   <workspaceRoot>

   to the active VS Code workspace, or to the current working directory if no workspace is open.

4. documentation

   (optional) — one or more URLs pointing to the API documentation. When provided (e.g., from a calling skill), these are used directly in Step 2 instead of searching.

{PROJECT_FOLDER}

1. WebSearch for the API's official documentation. Search for:
   • Official REST API reference (e.g.,

     "{apiName} REST API reference"

     )
   • OpenAPI / Swagger specification (e.g.,

     "{apiName} OpenAPI spec"

     )
   • Developer portal or API explorer
2. Prioritize machine-readable sources — OpenAPI specs and structured REST references are more useful than blog posts or tutorials because they contain exact field types, required/optional markers, and schema definitions that downstream agents need.
3. Select the most authoritative sources and document your selections with reasoning. Typically you need two sources: the human-readable API reference (for context and examples) and a machine-readable spec (for exact schemas).
4. WebFetch the selected documentation pages to confirm they are accessible and contain endpoint documentation. If a source is broken or unhelpful, find an alternative.

references/examples.md

• Create →

  test-setup

  — create test entities before running the use case
• List/Search →

  test-validation

  — verify operations worked
• Delete →

  test-cleanup

  — clean up after tests
• Read/Update → fill out the CRUD surface if endpoints exist

test-setup

test-validation

test-cleanup

—

"Will the API return an error if I create the primary entity WITHOUT providing a reference to this entity?"

• YES → Secondary entity — include it. The validation loop must create this before creating the primary entity.
• NO → Excluded — optional relationship, skip it.

• Create the dependency chain bottom-up (e.g., create Project before Issue)
• Delete the dependency chain top-down (e.g., delete Issue before Project)

• Primary endpoint catalog — these become OpenAPI operations. Use this table format:

| Use Case Action | Method | Path | Path Parameters | Has Body | Content Type |
|---|---|---|---|---|---|
| {action} | {method} | {path} | {params or —} | {Yes/No} | {content type} |

• Entity list with identifier fields — these become schema definitions

• Full CRUD endpoint catalog (primary + secondary) with lifecycle purpose labels — the validation loop uses

  test-setup

  endpoints to create test data,

  test-cleanup

  to delete it
• Dependency graph with field references (Mermaid diagram) — determines operation ordering
• Creation order (bottom-up) and deletion order (top-down) — use inline arrow notation (

  →

  ) on a single line per order (e.g.,

  Create A → Create B → Create C

  ), not numbered lists
• Pre-existing dependencies with discovery endpoints — the validation loop calls these to get valid values instead of trying to create
• Decision log — consolidate ALL dependency decisions (included as secondary, pre-existing, excluded) with reasoning into a single table so the validation loop can review why each entity was or was not included

• Auth scheme identified from documentation (if discoverable at this stage): type (Bearer, API Key, Basic, OAuth), required credential keys, header format
• If auth details are not yet clear, note this as a gap for deep research in Step 9

• Research order: secondary entities first (bottom of dependency tree), then primary. This way, when documenting a primary entity, its dependency details are already known.
• Scope: total entities to research, total endpoints discovered
• Excluded entities with reasoning

1. Research API-level notes first (auth scheme and rate limits — these apply globally)
2. Document pre-existing entities next (lightweight treatment — discovery schema only)
3. Research secondary entities in bottom-up order (bottom of dependency tree first)
4. Research primary entities last

1. The discovery endpoint's response schema — what fields come back from the List/Get endpoint
2. The field to extract — which field the downstream consumer needs (e.g.,

   id

   ,

   name

   ) and its type

1. ALWAYS check for cursor-based pagination FIRST — look for:

   continuation

   ,

   continuation_token

   ,

   next_cursor

   ,

   cursor

   ,

   after

   ,

   before

   ,

   next_page_token

   ,

   offset

   (when it's a token/string, not numeric).
2. Distinguish offset vs cursor: Offset uses NUMERIC values (0, 10, 20...). If a parameter named

   offset

   contains TOKEN/STRING values like

   "eyJ0eXAi..."

   , it's cursor-based, NOT offset.
3. Some APIs include both cursor tokens AND page metadata (page_count, page_number) in responses — the actual pagination mechanism is cursor-based. Always use cursor-based when a continuation/cursor token exists.
4. Only use page-based pagination if documentation explicitly shows "page" parameters AND no cursor indicators exist.
5. Each endpoint has EXACTLY ONE pagination type. NEVER mix types.
6. Search documentation for

   "{apiName} pagination"

   to find official patterns.

**List — GET `/path`**
- **Pagination type:** offset | cursor | page | timestamp | none
- **Items field:** {dot-notation path to items array, e.g., "data", "results", "values"}

- **Cursor param:** {query parameter name, e.g., "cursor", "after", "nextToken"}
- **Reference type:** marker | uri
- **Reference expression:** {dot-notation path to next cursor value, e.g., "pagination.nextCursor"}

• Use

  marker

  when the response contains a cursor VALUE (token/string).
• Use

  uri

  when the response contains a complete URL for the next page.
• NEVER use any other value for reference type — only

  marker

  or

  uri

  .

- **Offset param:** {query parameter name, e.g., "startAt", "offset"} — must be NUMERIC
- **Initial offset value:** {number, typically 0}

- **Page number param:** {query parameter name, e.g., "page", "pageNumber"}
- **Initial page number:** {number, typically 0 or 1}

- **Timestamp param:** {query parameter name, e.g., "since", "after"}

• {PROJECT_FOLDER}/action-plan.md

  from Step 8

• {PROJECT_FOLDER}/api-reference.md

  from Step 9 (the deep research file)

1. Read

   action-plan.md

   and extract:
   • Use case endpoint table (from §1 For Spec Generation)
   • Full CRUD endpoint catalog (from §2 For Live Validation)
   • Mermaid dependency graph (from §2)
   • Creation order and deletion order (from §2)
   • Pre-existing dependencies table (from §2)
   • Decision log table (from §2)
   • Auth scheme details (from §3 For Credential Collection)
   • Documentation source URL (from the header)
2. Read

   api-reference.md

   (Step 9 deep research) and note:
   • API-Level Notes content (Auth Scheme + Rate Limits) — this will become the top-level Authentication and Rate Limits sections
   • All entity sections (Pre-Existing, Secondary, Primary) with their full category detail
3. Write the final

   api-reference.md

   following the exact template below. Use the Write tool to overwrite the Step 9 file with the consolidated output.

• Service: {apiName}
• API Version: {version from documentation, e.g., "v3", "v1", "2023-08-01"}
• Base URL: {base URL from API-Level Notes}
• Documentation: {primary documentation URL from action plan header}

• Type: {Bearer / Basic / API Key / OAuth}
• Header format: {exact header pattern, e.g.,

  Authorization: Basic base64({email}:{api_token})

  }
• Required credentials: {credential key names, e.g.,

  BASIC_USERNAME

  ,

  BASIC_PASSWORD

  } {include any additional auth details from the deep research — alternative auth methods, transport requirements, test mode info}

• Creation order: {bottom-up arrow notation from action plan}
• Deletion order: {top-down arrow notation from action plan}

• ## Pre-Existing Entities

  ,

  ## Secondary Entities

  ,

  ## Primary Entities

• ### {Entity} [TYPE]

• #### Category N: {name}

## Entity Reference

• ### Pre-Existing Entities

  ,

  ### Secondary Entities

  ,

  ### Primary Entities

• #### {Entity} [TYPE]

• ##### Category N: {name}

api-reference.md

• Title is

  # {Service} API Reference

  (no "Deep Research" suffix)
• Overview section with base URL
• Authentication section with type, header format, required credentials
• Rate Limits & Constraints section
• Use Cases table with all use cases from input
• Entity Dependency Graph with Mermaid diagram
• Creation order and deletion order (inline arrow notation)
• Pre-existing dependencies table (or "None" statement)
• Decision log table
• Full CRUD Endpoint Catalog with lifecycle labels
• Entity Reference section contains every entity from Step 9
• All 6 per-entity categories preserved for each secondary and primary entity
• Pre-existing entities have discovery-only treatment (no request schemas, field catalogs)
• No duplicated API-Level Notes in Entity Reference

• OpenAPI version 3.0.x.
• Complete

  info

  section:

  title

  ending with "API", semver

  version

  (e.g.,

  1.0.0

  ), and a one-sentence imperative

  description

  .

• servers

  section with the base URL (including the API version prefix if the API uses one).

• paths

  section with ONLY the endpoints documented in

  api-reference.md

  's Use Cases table — do NOT add endpoints beyond what the research discovered.

• components

  section with: authentication schemes from §Authentication, reusable schemas for request/response bodies, common parameters, error responses.
• For each endpoint: complete parameter definitions (path, query, header, body), full response schemas with data types, error responses (4xx, 5xx), authentication requirements.
• Add ONE connectivity-test endpoint if the API has an obvious lightweight "ping" endpoint (e.g.,

  GET /me

  ,

  GET /health

  ). This single extra operation gives Step 12's prerequisites a way to verify credentials before the full loop runs. If the API has no such endpoint, do not invent one — Step 12 will use the first GET in

  paths

  instead.

• API version (e.g.,

  /v3

  ) MUST be in

  servers[].url

  , NOT in endpoint paths.
• Remove ALL API version prefixes from endpoint paths.
• Endpoint paths MUST NOT end with a trailing slash.

servers:
  - url: https://api.example.com/v3
paths:
  /users:
    get: ...
  /users/{id}:
    get: ...

servers:
  - url: https://api.example.com
paths:
  /v3/users:
    get: ...
  /users/{id}/:
    get: ...

• Every operation has a unique

  operationId

  in camelCase (e.g.,

  listCourses

  ,

  getCourseById

  ).
• Every operation has a

  description

  (imperative voice, one sentence).
• Every operation has at least one request example and at least one response example.
• Every property in every schema has a

  description

  .
• Strings with constrained values use

  enum

  (no naked strings).

• required

  fields are explicit on every object schema where applicable.
• Path and query parameters have descriptions and types.

• Read

  {PROJECT_FOLDER}/<apiName>.yaml

  .
• Verify it is valid YAML.
• Verify it contains an

  openapi

  key with a value starting with

  3.

  (OpenAPI 3.x).
• Verify

  paths

  contains at least one operation.
• Count the total number of operations — this is M, the denominator in the progress line (

  N/M

  ).

• Read

  {PROJECT_FOLDER}/api-reference.md

  .
• Verify it contains these sections: Authentication, Entity Dependency Graph, Full CRUD Endpoint Catalog, Entity Reference.
• Read the Authentication section and extract:
  • Auth type (e.g., Bearer token, Basic, API Key)
  • Header format (e.g.,

    Authorization: Bearer <TOKEN>

    )
  • Required credential key name(s) (e.g.,

    CODA_API_TOKEN

    )
  • For API Key auth: injection location — header name (e.g.,

    X-API-Key

    ) or query parameter name(s) (e.g.,

    key

    ,

    token

    )

{PROJECT_FOLDER}/config.properties

1. Take the credential key name(s) extracted in step 2 (e.g.,

   CODA_API_TOKEN

   , or

   TRELLO_API_KEY

   and

   TRELLO_API_TOKEN

   ).
2. Generate a placeholder value for each key by lower-casing the key name, replacing underscores with hyphens, and wrapping with

   your-

   and

   -here

   (e.g.,

   CODA_API_TOKEN

   →

   your-coda-api-token-here

   ).
3. Create

   {PROJECT_FOLDER}/config.properties

   with one

   KEY=placeholder

   line per credential:
   bash

   printf '%s\n' 'CODA_API_TOKEN=your-coda-api-token-here' > {PROJECT_FOLDER}/config.properties

   For multiple keys, write all lines in one command:
   bash

   printf '%s\n' 'TRELLO_API_KEY=your-trello-api-key-here' 'TRELLO_API_TOKEN=your-trello-api-token-here' > {PROJECT_FOLDER}/config.properties

4. Report to the user and wait:

   Created config.properties with placeholder credentials:
   
     CODA_API_TOKEN=your-coda-api-token-here
   
   Please replace the placeholder value(s) with real credentials and let me know when ready.

   ▸ WAIT — Do not proceed until the user confirms the credentials are in place.
5. Once the user confirms, proceed to verify keys below.

• For each credential key identified in step 2, verify the key exists:
  bash

  grep -c '^CREDENTIAL_KEY=' {PROJECT_FOLDER}/config.properties

  The result must be

  1

  . Do NOT read or display the value.

• Read the Overview section of

  api-reference.md

  and extract the

  Base URL

  value (e.g.,

  https://coda.io/apis/v1

  ).
• Verify it starts with

  https://

  or

  http://

  .

1. Cross-reference with the Entity Reference section of

   api-reference.md

   to determine which entity the parameter refers to.
2. Build a deduplicated set of

   (parameter_name, entity_type, description)

   .

The operations in this spec require the following entity IDs:

- `docId` (string) — references a Doc entity. Used by 8 operations. Please provide an existing Doc ID.
- `pageIdOrName` (string) — references a Page entity. Used by 4 operations. Please provide an existing Page ID or name.

completed = 0

passed = 0

fixed = 0

failed = 0

skipped = 0

auth_halted = false

any_2xx_seen = false

• attempt_count = 0

  — incremented every time a curl request is executed for this operation.

• retry_history = []

  — after each attempt, append:

  { attempt_number, status_code, error_summary, fix_applied_if_any }

  .

• last_failure_signature = null

  — the

  (status_code, error_message_key)

  pair from the most recent failed attempt.

1. Set the current operation to

   (method, path)

   .
2. Operation Analysis — Step 13.1.
3. Request Execution and Response Validation — Step 13.2.
4. If

   auth_halted

   is true, exit the loop immediately — do NOT proceed to steps 5–9. Jump to Step 14.
5. Increment

   completed

   .
6. Classify the result (

   passed

   ,

   fixed

   ,

   failed

   , or

   skipped

   ) and update the corresponding counter.
7. Emit the progress line:

   Validation: {completed}/{M} | passed {X} | fixed {Y} | failed {Z}

   — append

   | skipped {S}

   only when

   skipped > 0

   .
8. If the operation failed, emit a detail line:

     ✗ {METHOD} {path}  {status_code} — {reason}

   .
9. Proceed to the next operation.

(method, path)

• HTTP method (GET, POST, PUT, DELETE, PATCH).
• Path template (e.g.,

  /docs/{docId}/pages/{pageIdOrName}

  ).
• Path parameters — for each: name, type, required (yes/no).
• Query parameters — for each: name, type, required, default value.
• Request body schema — if the method has a

  requestBody

  definition (typically POST, PUT, PATCH). Extract required fields and their types.
• Expected success response — the 2XX status code declared in the spec's

  responses

  section (e.g.,

  200

  ,

  201

  ,

  202

  ). If multiple 2XX codes exist, note all of them.
• Response body schema — the schema under

  responses.{status}.content.application/json.schema

  . If the schema uses

  $ref

  , resolve the reference by looking up

  components/schemas/{name}

  in the spec. If no response body is defined (e.g., 204), note "no body."
• Security requirements — which security scheme the operation uses (from the operation-level or spec-level

  security

  field).

https://coda.io/apis/v1/docs/AbCDeFGH/pages/canvas-abc123

-X

-X GET

-X POST

api-reference.md

config.properties

• Bearer token:
  bash

  -H "Authorization: Bearer $(grep '^CODA_API_TOKEN=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-)"

• Basic auth:
  bash

  -H "Authorization: Basic $(echo -n "$(grep '^API_USER=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-):$(grep '^API_PASS=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-)" | base64)"

• API Key (header):
  bash

  -H "{header_name}: $(grep '^API_KEY=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-)"

• API Key (query parameter): Append the credential as a URL query parameter. Use

  ?

  for the first parameter,

  &

  for subsequent ones:
  bash

  "https://api.example.com/endpoint?{param_name}=$(grep '^API_KEY=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-)"

  For APIs requiring multiple query-parameter credentials (e.g., separate

  key

  and

  token

  params):
  bash

  "https://api.example.com/endpoint?key=$(grep '^TRELLO_API_KEY=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-)&token=$(grep '^TRELLO_API_TOKEN=' {PROJECT_FOLDER}/config.properties | cut -d'=' -f2-)"

  If the URL already has query parameters (from 13.1.2 required query params), append with

  &

  .

-H "Content-Type: application/json"

-d '{...}'

-s -w "\n%{http_code}" -D /tmp/validation_headers.txt

Retry-After

• DELETE (any entity) — always destructive.
• PUT that replaces an entire entity — destructive (overwrites existing state).

1. Warn the user before executing:

   ⚠️  Destructive operation: {METHOD} {path}
   This will {consequence} the {entity_type} with ID `{entity_id}`.
   This action may not be reversible.
   
   Proceed? (yes / skip)

   Where

   {consequence}

   is:
   • DELETE → "permanently delete"
   • PUT → "overwrite all fields of"
2. If the user says "yes" (or equivalent affirmative) → proceed to 13.2.3 and execute the request.
3. If the user says "skip" (or equivalent negative) → do NOT execute the request. Classify the operation as skipped. Increment the

   skipped

   counter. Emit a progress line with a skip detail:

     ⏭ {METHOD} {path}  skipped — user declined destructive operation

   Proceed directly to 13.2.7. Do not count this as a failure.

• Status code: the last line of output (from

  -w "\n%{http_code}"

  ).
• Response body: all lines except the last. If empty, the response has no body.
• Response headers: available in

  /tmp/validation_headers.txt

  if needed by error handlers (e.g.,

  Retry-After

  for 429 responses).

any_2xx_seen = true

1. Look up the error response schema in the spec for the actual status code:

   responses.{status_code}.content.application/json.schema

   . If no schema is defined for this specific status code, also check for a

   default

   response schema.
2. If no error schema exists in the spec → skip schema checking.
3. If an error schema exists and the response has a body → compare the error body against the schema using the same comparison logic from 13.2.7 Branch A (steps 1–6).
4. If mismatches are found → apply the same auto-fix strategies from 13.2.7 to correct the error schema in the spec. Write the updated spec to disk and log the fixes.
5. No re-validation is needed for error schemas — the error itself still stands. The agent is only correcting the spec's description of the error response format.

1. Classify the failure context:
   • If

     any_2xx_seen == false

     → permanent auth failure (wrong credentials or insufficient permissions).
   • If

     any_2xx_seen == true

     → mid-session token expiration (credentials worked before but have now expired).
2. Record the auth failure:
   • Set

     auth_halted = true

     .
   • Note the current operation

     (method, path)

     and the status code (401 or 403).
   • Note the failure context (permanent or mid-session).
3. Emit a halted progress line:

   Validation: {completed}/{M} | passed {X} | fixed {Y} | failed {Z} | AUTH HALTED
     ⛔ {METHOD} {path}  {status_code} — {reason from response body}

   Use

   ⛔

   (not

   ✗

   ) to visually distinguish auth halts from normal failures.
4. Do NOT increment

   completed

   or

   failed

   — the operation was not fully processed.
5. Do NOT proceed to 13.2.7 or 13.2.8.
6. Return to the validation loop, which checks

   auth_halted

   and exits to Step 14.

• Classify as failed with reason "server error ({status_code})" (e.g., "server error (503)").
• Do NOT retry the operation.
• Skip 13.2.7 and proceed directly to 13.2.8 to record the result.

1. Identify the suspect path parameter(s):
   • Extract all path parameters from the current operation's path template.
   • For each path parameter, note the value currently substituted (from the stored entity ID map).
   • If the path has multiple parameters, use the response body to infer which entity was not found. If the response body does not indicate which parameter is wrong, suspect the most specific (deepest-nested) parameter first.
2. Ask the user for a corrected entity ID:
   If one parameter is clearly suspect:

   404 Not Found — {METHOD} {path}
   
   The API returned 404, which means the entity referenced by `{suspect_param}`
   (current value: `{current_value}`) was not found.
   
   Please provide a valid {entity_type} ID for `{suspect_param}`:

   If multiple path parameters might be wrong:

   404 Not Found — {METHOD} {path}
   
   The API returned 404. The following entity IDs may be incorrect:
   - `{param1}` (current value: `{value1}`) — {entity_type_1}
   - `{param2}` (current value: `{value2}`) — {entity_type_2}
   
   Please provide corrected values (or confirm if a value is correct):

3. Update stored entity IDs: after the user provides corrected value(s), update the stored entity ID map so that all subsequent operations using the same parameter name(s) will use the corrected value(s).
4. Reconstruct and retry:
   • Rebuild the curl command from 13.2.1 using the corrected entity ID(s).
   • If the operation is destructive (DELETE or PUT), re-trigger the 13.2.2 destructive operation confirmation before executing.
   • Execute the rebuilt curl command (13.2.3) and parse the response (13.2.4).
5. Evaluate the retry result:
   • 2XX response → the corrected ID worked. Proceed to 13.2.7 for schema validation as normal.
   • 404 again (same error) → classify as failed with reason "404 — entity not found (user-provided ID also not found)". Do NOT ask the user again. Proceed to 13.2.8.
   • Different non-2XX error → pass the new error through 13.2.5 and 13.2.6 as if it were the initial response.
6. Retry limit: one user-interactive retry per 404. If the retry itself returns 404, fail immediately.

attempt_count < 10

1. Tier 1 — Error message diagnosis:
   • Parse the error response body for actionable details (e.g., "field X is required", "invalid value for parameter Y", "unknown field Z").
   • If the message identifies a specific field, constraint, or format issue:
     • Fix the request accordingly (add missing field, correct a value, remove an invalid field).
     • Re-execute the curl command (13.2.3) and parse the response (13.2.4).
     • 2XX → proceed to 13.2.7 (schema validation).
     • Still 400 → check progress gate. If no progress, classify as failed and proceed to 13.2.8. If progress, escalate to Tier 2.
     • Different non-2XX → pass through 13.2.5 and 13.2.6 for the new error code. The 400 tier sequence does NOT continue.
   • If the message is NOT actionable → skip directly to Tier 2 without retrying.
2. Tier 2 —

   api-reference.md

   consultation:
   • Read the relevant sections of

     api-reference.md

     :
     • Entity Reference for the entity being operated on — required fields, field types, enum values, constraints.
     • CRUD Endpoint Catalog for the current endpoint — request body format, required parameters.
   • Compare the current request against the documented requirements.
   • Identify discrepancies and reconstruct the request to match the documented format.
   • Re-execute the curl command (13.2.3) and parse the response (13.2.4).
   • 2XX → proceed to 13.2.7.
   • Still 400 → check progress gate. If no progress, classify as failed and proceed to 13.2.8. If progress, escalate to Tier 3.
   • Different non-2XX → pass through 13.2.5 and 13.2.6 for the new error code.
3. Tier 3 — Official API documentation research:
   • Use WebSearch and/or WebFetch to find the official SaaS API documentation for this endpoint.
   • Look for: required fields, field format/constraints, valid values, API-specific validation rules not captured in

     api-reference.md

     .
   • Apply any discovered fixes to the request.
   • Re-execute the curl command (13.2.3) and parse the response (13.2.4).
   • 2XX → proceed to 13.2.7.
   • Still 400 → classify as failed with reason "400 — {error message} (all remediation tiers exhausted)". Proceed to 13.2.8.
   • Different non-2XX → pass through 13.2.5 and 13.2.6 for the new error code.

1. Check for

   Retry-After

   header:
   • Read

     /tmp/validation_headers.txt

     and look for a

     Retry-After

     header (case-insensitive).
   • If present as an integer (e.g.,

     Retry-After: 5

     ) → wait duration is that many seconds.
   • If present as an HTTP date → compute seconds until that time. If the date is in the past, treat as 0.
   • Cap: if the computed wait exceeds 120 seconds, cap at 120 seconds.
   • If no

     Retry-After

     header is present → use exponential backoff (step 2).
2. Exponential backoff (when no

   Retry-After

   header):
   • First 429: wait 2 seconds.
   • Second consecutive 429: wait 4 seconds.
   • Third consecutive 429: wait 8 seconds.
   • Continue doubling, capped at 120 seconds per wait.
3. Wait and retry:
   • Execute

     sleep {seconds}

     via Bash to wait the computed duration.
   • Re-execute the same curl command (13.2.3) and parse the response (13.2.4).
4. Evaluate the retry result:
   • 2XX → rate limit cleared. Proceed to 13.2.7 for schema validation.
   • 429 again → still rate-limited. Repeat from step 1.
   • Different non-2XX → pass through 13.2.5 and 13.2.6 for the new status code. The 429 retry sequence does NOT continue.
5. Progress gate exception: repeated 429s bypass the progress gate. Before each retry, verify

   attempt_count < 10

   .
6. Exhaustion: if the absolute ceiling (10 attempts) is reached and the response is still 429, classify as failed with reason "429 — rate-limited (retry limit reached after {N} attempts)". Proceed to 13.2.8.
7. Silent operation: do NOT emit progress lines during 429 waits. Only emit the final result when the operation completes.

• 409 Conflict: look for resource name/ID conflicts — change the conflicting value.
• 422 Unprocessable Entity: look for field-level validation failures — correct the field.
• 405 Method Not Allowed: check for an

  Allow

  response header listing valid methods — correct the HTTP method.

(HTTP status code, key error details)

last_failure_signature

• Different = forward progress. Allow retry (subject to ceiling).
• Same = no progress. Stop retrying immediately — classify as failed (unresolvable) and proceed to 13.2.8.

attempt_count

attempt_count < 10

• Total

  attempt_count

  .
• Whether stopped by "no progress" (progress gate) or "retry limit reached" (ceiling).
• The full

  retry_history

  .

1. Parse the response body as JSON. If parsing fails, report "Response is not valid JSON" and stop.
2. Resolve the spec schema. Read the response schema for the matched status code from the spec. If it uses

   $ref

   , follow the reference to

   components/schemas/{name}

   and expand it. Continue resolving any nested

   $ref

   references.
3. Compare fields. For each field in the response:
   • Check if the field is defined in the spec schema's

     properties

     .
   • If defined, check that the JSON type matches the schema type:

     • string

       ↔ string

     • integer

       or

       number

       ↔ number

     • boolean

       ↔ boolean

     • array

       ↔ array

     • object

       ↔ object
   • If the field is NOT in the schema, note it as an extra field.
4. Check required fields. For each field in the schema's

   required

   array, verify the field exists in the response. If missing, note it as a missing required field.
5. Check nested objects (one level). For fields of type

   object

   that have a

   properties

   definition in the schema, repeat steps 3–4 on the nested object.
6. Check arrays. For fields of type

   array

   , verify the response value is an array. If the schema defines

   items

   , compare the first array element against the

   items

   schema (if the array is non-empty).
7. Determine result:
   • If NO mismatches found → classify as passed. Proceed to 13.2.8.
   • If mismatches found → apply the auto-fix strategies below, then re-validate.

type

properties

required

required

required

properties

components/schemas/{name}

$ref

{schema_name}.{field_path}: {mismatch_type} — {description of change}

1. Re-execute the same curl command from 13.2.3 (always use a fresh response).
2. Parse the response using 13.2.4 logic.
3. If the response is still 2XX, repeat the schema comparison (Branch A steps 1–6) using the updated spec schema.
4. Evaluate:
   • No mismatches → classify as fixed. Proceed to 13.2.8.
   • Mismatches remain but are different from the previous attempt → forward progress. Apply additional fixes and re-validate.
   • Mismatches remain and are identical → no progress. Classify as failed with reason "schema mismatch (auto-fix unsuccessful)". Proceed to 13.2.8.
   • Non-2XX response on re-validation → classify as failed with the error status code and reason. Proceed to 13.2.8.
5. Schema auto-fix retries share

   attempt_count

   with the error handlers — do not exceed 10 total attempts.

• Validate that the actual HTTP status code matches the expected status code from the spec.
• If it matches → classify as passed.
• If it does not match → classify as failed with reason "status code mismatch" (report actual vs. expected).

• passed — 2XX response, schema matched (or no body, status matched). Includes operations that succeeded after 404 entity ID correction.
• fixed — 2XX response, schema did not match initially, but the agent auto-fixed the spec and re-validation succeeded.
• failed — non-2XX response after all remediation, OR 2XX response where schema auto-fix could not resolve all mismatches after retries.
• skipped — user declined to execute a destructive operation after the 13.2.2 confirmation prompt.

Validation: 1/5 | passed 1 | fixed 0 | failed 0
Validation: 2/5 | passed 1 | fixed 0 | failed 1
  ✗ POST /docs/{docId}/pages  400 — missing required field: name (3 attempts)
Validation: 3/5 | passed 2 | fixed 0 | failed 1

• One progress line per completed operation.
• Detail line ONLY for failed operations (during the loop). When

  attempt_count > 1

  , append

  ({attempt_count} attempts)

  .
• Record the

  retry_history

  for failed ops and the fix summary for fixed ops — Step 14 may emit them in the final report.
• Fixed operations count as successes in the progress — no detail line in the loop.
• Do NOT print detail lines while the agent is still attempting remediation.

| skipped {S}

skipped > 0

Validation complete: 5/5 | passed 2 | fixed 1 | failed 1 | skipped 1

  ✔ GET /docs/{docId}  fixed — Doc.owner: type mismatch (object → string), Doc.sourceDoc: structural mismatch (string → object)
  ✗ POST /docs/{docId}/pages  400 — missing required field: name (3 attempts)
  ⏭ DELETE /docs/{docId}  skipped — user declined destructive operation

• Fixed (✔):

    ✔ {METHOD} {path}  fixed — {fix_summary}

  . When

  attempt_count > 1

  , append

  ({attempt_count} attempts)

  .
• Failed (✗):

    ✗ {METHOD} {path}  {status_code} — {reason}

  . When

  attempt_count > 1

  , append

  ({attempt_count} attempts)

  .
• Skipped (⏭):

    ⏭ {METHOD} {path}  skipped — user declined destructive operation

  .

{N} operation(s) could not be validated. How would you like to proceed?

1. Provide additional information so I can retry the failed operations
2. Keep the failed operations in the spec as-is (no changes to their definitions)
3. Remove the failed operations from the spec and proceed with the corrected spec
4. Cancel — stop the validation process

• Option 1: Present the

  retry_history

  for each failed operation so the user understands what was already tried. Accept the user's additional information, then re-run validation for just the failed operations. After re-validation, present an updated summary and repeat the decision flow if failures remain.
• Option 2: Pass the spec forward as-is. Auto-fixes applied during validation are already written to disk.
• Option 3: Remove the failed operations from the spec's

  paths

  object using the Edit tool. Write the updated spec to disk.
• Option 4: Stop. Do not pass the spec forward.

Knowledge ready: {PROJECT_FOLDER}
  - api-reference.md
  - {apiName}.yaml
  - config.properties

failed == 0

Knowledge ready: {PROJECT_FOLDER}
  - api-reference.md
  - {apiName}.yaml
  - config.properties

build-mule-integration

api-reference.md

<apiName>.yaml