Skip to content

feat(client): add getSchema to fetch endpoint JSON schemas#191

Open
tombeckenham wants to merge 4 commits intofal-ai:mainfrom
tombeckenham:189-feat-model-runtime-schemas
Open

feat(client): add getSchema to fetch endpoint JSON schemas#191
tombeckenham wants to merge 4 commits intofal-ai:mainfrom
tombeckenham:189-feat-model-runtime-schemas

Conversation

@tombeckenham
Copy link
Copy Markdown

@tombeckenham tombeckenham commented Feb 5, 2026

Summary

  • Adds getSchema(endpointId) method to fetch input/output JSON schemas for any fal endpoint
  • Schemas are fully resolved with all $ref references inlined, making them suitable for JSON Schema validators or LLM tool definitions
  • Handles circular references by collecting them into $defs and converting circular $ref paths to #/$defs/Name format

Benefits

  • LLM tool definitions — Pass resolved schemas directly to LLMs as tool/function definitions, enabling AI agents to call fal endpoints with proper parameter descriptions
  • Input validation — Validate requests locally before sending, catching errors earlier with better messages
  • Dynamic form generation — Build UIs that automatically generate input forms based on endpoint schemas
  • Discoverability — Programmatically explore what any endpoint accepts and returns

Usage

const { input, output } = await fal.getSchema("fal-ai/kling-video/v3/pro/image-to-video");
// input and output are fully resolved JSON schemas

Test plan

  • Unit tests cover schema resolution including circular dependencies
  • Manual test with fal.getSchema("fal-ai/kling-video/v3/pro/image-to-video") returns valid input/output schemas

Fixes #189

@tombeckenham
Copy link
Copy Markdown
Author

@drochetti what do you think of this approach to get schemas?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: model runtime schemas

1 participant