[DOCS-1532] Fix inaccurate delete-batch and delete-run API docs samples

[rosalie-byrnes]

Context

Two in-site feedback reports flagged inaccurate code samples on:

• https://docs.instabase.com/api-sdk/api-reference/batches/delete-batch
• https://docs.instabase.com/api-sdk/api-reference/runs/delete-run

The reports included no further detail beyond there being code sample issues.

As I'm not involved in the backend, I set Cursor in the issue. To investigate, I asked Cursor to verify the published samples against:

1. This OpenAPI spec (source of the Fern docs)
2. The published Python SDK (instabase-aihub 0.14.0)
3. The Instabase monorepo server handlers for these endpoints
4. A local Fern docs preview after temporarily copying this branch’s spec into instabase-fern

What Cursor found

Delete run — real defects

1. Python “without SDK” sample raised KeyError when indexing delete_input_dir_job_id / delete_output_dir_job_id / delete_log_dir_job_id directly. The server omits those keys when the matching query flag is false (or when that filesystem delete is not enqueued). It does not return null. Verified in py/src/instabase/jobs/job_handler.py (delete_job_ids starts empty; keys are inserted only inside the corresponding if delete_input: / if delete_output: / if delete_logs: branches) and returned verbatim as the 202 payload from apps.py.
2. Python “with SDK” sample could loop forever if a deletion job ended in FAILED or CANCELLED. The sample only removed job IDs on COMPLETE. Terminal states confirmed in file_service.proto (COMPLETE, FAILED, CANCELLED) and surfaced by the shared job-status handler.
3. Fern-generated language snippets used a literal run_id in the URL (for example .../apps/runs/run_id), which 404s if copy-pasted. Cause: the run_id path parameter had no example value, so Fern fell back to the parameter name.

Delete batch — no broken Python sample, but related polish and shared docs issues

The delete-batch Python samples matched the API/SDK behavior (202 + {"job_id": ...}, polled successfully). Remaining issues were:

1. The sample used the legacy client.batches.poll_job() path, while the preferred equivalent is client.jobs.status() (already documented on the poll-batches-job page as preferred).
2. The sample exited on any non-PENDING/RUNNING state without telling the reader when deletion failed.
3. Prose links from delete-batch still pointed readers at the legacy poll-batches-job page even after the sample switched to the preferred method.
4. Shared with delete-run: missing path-parameter example values caused weak/placeholder URLs in generated language tabs (integer params fell back to values like 1 / 0).

Fixes in this PR

Delete run

• Python “with SDK”: treat COMPLETE, FAILED, and CANCELLED as terminal; report non-success terminal states; skip the final sleep when done.
• Python “without SDK”: print job IDs only when present (if key in job_ids), matching server “omit key” behavior.
• 202 response description: clarify async acceptance, that keys are absent when the corresponding option is false, and link to job-status polling.
• Response schema: remove incorrect nullable: true from the three job-ID properties; describe when each key is returned.

Delete batch

• Python “with SDK”: switch polling from client.batches.poll_job() to preferred client.jobs.status(); report when the terminal state is not COMPLETE.
• Retarget “checked for completion” / “Poll the job ID” / job_id field links from legacy poll-batches-job to preferred /jobs/job-status.

Legacy poll-batches-job page (kept)

• Kept the endpoint and its samples for backward compatibility.
• Clarified the existing Info callout: maintained for compatibility, but an outdated way to check status; prefer poll file operation job status / client.jobs.status().

Path-parameter examples (docs rendering)

• Added example values for batch_id, run_id, and both job_id path parameters so Fern-generated snippets substitute real example values instead of parameter-name placeholders.

Testing

• Extracted the updated Python samples from this spec and executed them against mocked SDK/requests layers covering:
  • happy path (COMPLETE)
  • terminal FAILED / CANCELLED (previously hung on delete-run)
  • missing job-ID keys (previously KeyError on delete-run)
  • delete-batch regression for both with/without SDK samples
• Verified SDK method signatures/response models against published instabase-aihub 0.14.0.
• Verified server behavior against the Instabase monorepo handlers/proto noted above.
• Temporarily copied this spec into a local fern docs dev preview and confirmed on localhost that:
  • delete-run generated JS URL uses the UUID example (no literal run_id)
  • delete-run response copy/schema descriptions match the fixes
  • delete-batch Python sample uses client.jobs.status()
  • Temporary fern copy was reverted afterward; this PR is aihub-openapi only

Next steps (outside this PR)

1. Optionally regenerate the Python SDK if we want generated models to drop the prior nullable marking on the delete-run 202 response fields (behaviorally optional either way; server never sends null).
2. Optional follow-up: other path parameters (filename, session_id, path, etc.) still lack example values and can produce similar placeholder URLs on their pages.

What to review

• Delete-run Python samples (with SDK + without SDK)
• Delete-batch Python “with SDK” sample and polling links
• Delete-run 202 schema/descriptions (keys omitted, not null)
• Legacy poll-batches-job Info callout still accurate
• Path-parameter example values look reasonable for generated snippets

Made with Cursor

[abhishek-ib]

lgtm, No breaking changes. But can you please hold off on merging this