API reference parameter descriptions audit

[truthixify]

Labels: Stellar Wave, audit, docs, drips, help-wanted, good-first-issue
Tier: M (2–4 days)
Type: audit + writing

Context

docs/api-reference/endpoints.mdx and docs/api-reference/types.mdx list signatures but every parameter is bare. Reading them, you see name: string but not "must be 3–32 lowercase alphanumeric characters; will be SHA-256 hashed for storage." That semantic information is the difference between docs and a noticeboard.

Scope

For every parameter and return field across the API reference:

1. Add a 1-sentence description.
2. Add constraints (min, max, regex, enum values) where applicable.
3. Add an example value in the description if the field is non-obvious.
4. Cross-reference related types — link chain: Chain to the Chain enum page.

Where the source-of-truth lives

• For SDK functions: the JSDoc (which should be improved via sdk/10 — they'll inform each other).
• For HTTP endpoints: the Spectre + Gateway DTOs in TypeScript.
• For ambiguous cases: source files — sdk/src/chains/*/types.ts, Spectre's agent/types.ts.

Style

• Each field gets one tight sentence. No multi-paragraph descriptions in tables.
• For required vs. optional, use Mintlify's standard tag styling (✓ required, ○ optional or similar).
• Don't editorialize — describe what the field is, not what the API designer's intent was.

Acceptance criteria

• Every parameter and return field in endpoints.mdx and types.mdx has a description.
• Constraints documented where applicable.
• Cross-references wired up.
• Reviewed against the actual source-of-truth for each section (no fabrication).

Why good-first-issue

Mechanical, well-scoped, no architectural decisions. The contributor learns the entire API surface by writing it, which is high-leverage onboarding for any future contributions.

[yui-stingray]

Hi, I would like to work on this issue as part of Stellar Wave.

I read the issue and the repository guidance and will wait for maintainer assignment before starting implementation or opening a PR. If assigned, I will keep the work focused on api-reference/endpoints.mdx and api-reference/types.mdx: add concise one-sentence descriptions for every parameter and return field, document constraints and example values only when supported by the source material, and wire up cross-references such as Chain where appropriate.

Before opening a PR, I will review the SDK/HTTP source-of-truth files mentioned in the issue, avoid fabricating ambiguous constraints, and run the repository docs/build checks available in this repo. I will also note any fields that need maintainer clarification instead of guessing.