fix(api): clarify and standardize endpoint descriptions

[waleedlatif1]

Summary

• Standardize endpoint and field descriptions around caller-visible behavior and remove unnecessary implementation details.
• Correct retry, archival, search coverage, dispatch, and credential guidance; regenerate API and CLI documentation.
• Add API description conventions and update the v2 API skill.

Type of Change

• Bug fix

Testing

Passed repository lint, all 46 audits, docs-manifest validation, workspace type-checks, 498 focused API tests, and 48 CLI/generator tests. Verified that generated API schemas are unchanged.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 8, 2026 3:09am UTC

[greptile-apps]

Greptile Summary

This PR standardizes caller-facing API descriptions while preserving endpoint behavior and regenerates the corresponding OpenAPI and CLI documentation.

• Clarifies archival, restoration, retry, retention, credential, pagination, and asynchronous-processing semantics.
• Adds conventions for concise, transport-neutral API documentation.
• Aligns shared schemas, generated OpenAPI specifications, CLI metadata, and CLI reference pages.
• The two previous findings are manually resolved, and their documented fixes remain present.

Confidence Score: 5/5

The PR appears safe to merge; no new actionable defects or outstanding previous findings remain.

The recent description changes agree with the corresponding upload, archival, restoration, sharing, dispatch, and retention behavior. Both previous threads were manually resolved, and the current contracts retain their fixes.

Important Files Changed

Filename	Overview
apps/sim/lib/api/contracts/v2/openapi/README.md	Adds conventions for concise, caller-visible, behaviorally accurate API descriptions.
apps/sim/lib/api/contracts/v2/openapi/files-audit.ts	Clarifies file lifecycle, upload, sharing, search, and folder-operation descriptions.
apps/sim/lib/api/contracts/v2/openapi/knowledge.ts	Standardizes knowledge-base, connector, document, upload, and folder descriptions.
apps/sim/lib/api/contracts/v2/openapi/tables.ts	Clarifies dispatch polling, asynchronous exports, and archival/restoration semantics.
apps/sim/lib/api/contracts/v2/openapi/workflows.ts	Standardizes workflow, run, file-download, and folder descriptions.
apps/sim/lib/api/contracts/v2/openapi/shared.ts	Rewords shared run-retention guidance without changing its documented behavior.
apps/sim/lib/api/contracts/logs.ts	Distinguishes the canonical trace-span duration field from its compatibility field.
apps/sim/lib/api/contracts/v2/workflows.ts	Retains qualified run-ID recovery guidance and clarifies selected-output usage.
packages/sim-cli/src/generated/v2-api.ts	Regenerates CLI API metadata from the revised source descriptions.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Contract and OpenAPI description sources] --> B[OpenAPI generation]
    A --> C[CLI metadata generation]
    B --> D[Generated API specifications]
    C --> E[Generated CLI client]
    C --> F[CLI reference documentation]
    G[Description conventions and tests] --> A

Loading

_{Reviews (3): Last reviewed commit: "fix(api): align descriptions across reso..." | Re-trigger Greptile}

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.