{"openapi":"3.1.0","info":{"title":"fal (BYOK) API","version":"0.1.0","description":"fal (BYOK) lets an AI assistant read your own fal data through the fal API with a key you supply (fal API key (a key on the API preset or one with read permissions)). Read-only: 12 tools (list_models, get_model_pricing, get_models_usage, get_models_analytics, list_workflows, list_serverless_apps, get_serverless_usage, get_app_queue, list_app_revisions, list_compute_instances, list_api_keys,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-fal.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-fal/docs"},"termsOfService":"https://connectorbay.com/byok-fal/terms"},"servers":[{"url":"https://byok-fal.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-fal/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_models":{"post":{"operationId":"list_models","summary":"Search the fal model catalog by text, category or status with endpoint id, display name, category, description, status a","description":"Search the fal model catalog by text, category or status with endpoint id, display name, category, description, status and tags. Use for \"Which fal text-to-image models are active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Free text to match model names, descriptions or categories.","title":"Q"},"category":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only this category, for example text-to-image, image-to-video or training.","title":"Category"},"status":{"anyOf":[{"enum":["active","deprecated"],"type":"string"},{"type":"null"}],"default":null,"description":"Only active or deprecated models.","title":"Status"},"sort":{"anyOf":[{"enum":["relevant","recent"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: relevant or recent.","title":"Sort"},"endpoint_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this endpoint id, for example fal-ai/flux/dev.","title":"Endpoint Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor for the next page.","title":"Cursor"}},"title":"list_modelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_model_pricing":{"post":{"operationId":"get_model_pricing","summary":"Get the unit price of one or more fal model endpoints: price, unit (such as image or second) and currency. Use for \"How ","description":"Get the unit price of one or more fal model endpoints: price, unit (such as image or second) and currency. Use for \"How much does fal-ai/flux/dev cost per image\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"endpoint_id":{"description":"Endpoint id, or several separated by commas (up to 50), for example fal-ai/flux/dev.","maxLength":2000,"title":"Endpoint Id","type":"string"}},"required":["endpoint_id"],"title":"get_model_pricingArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_models_usage":{"post":{"operationId":"get_models_usage","summary":"Summarize your spend on fal model endpoints over a time window: quantity, unit price and cost per endpoint. Needs a key ","description":"Summarize your spend on fal model endpoints over a time window: quantity, unit price and cost per endpoint. Needs a key with usage access. Use for \"How much did I spend on each fal model this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window, ISO 8601 date or time such as 2026-10-01. Defaults to 24 hours ago.","title":"Start"},"end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window (exclusive), ISO 8601. Defaults to now.","title":"End"},"endpoint_id":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Only this endpoint id, or several separated by commas.","title":"Endpoint Id"},"expand":{"anyOf":[{"enum":["summary","time_series"],"type":"string"},{"type":"null"}],"default":"summary","description":"What to include: summary (totals per endpoint) or time_series (buckets over time).","title":"Expand"},"timeframe":{"anyOf":[{"enum":["minute","hour","day","week","month"],"type":"string"},{"type":"null"}],"default":null,"description":"Bucket size for time_series.","title":"Timeframe"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor for the next page.","title":"Cursor"}},"title":"get_models_usageArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_models_analytics":{"post":{"operationId":"get_models_analytics","summary":"Summarize request counts, errors, latency percentiles and cold boots of fal model endpoints you called. An endpoint id i","description":"Summarize request counts, errors, latency percentiles and cold boots of fal model endpoints you called. An endpoint id is required. Use for \"What was the error rate and p95 latency of fal-ai/flux/dev for my requests\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"endpoint_id":{"description":"Endpoint id, or several separated by commas (up to 50).","maxLength":2000,"title":"Endpoint Id","type":"string"},"start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window, ISO 8601 date or time such as 2026-10-01. Defaults to 24 hours ago.","title":"Start"},"end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window (exclusive), ISO 8601. Defaults to now.","title":"End"},"expand":{"anyOf":[{"enum":["summary","time_series"],"type":"string"},{"type":"null"}],"default":"summary","description":"What to include: summary (totals per endpoint) or time_series (buckets over time).","title":"Expand"},"timeframe":{"anyOf":[{"enum":["minute","hour","day","week","month"],"type":"string"},{"type":"null"}],"default":null,"description":"Bucket size for time_series.","title":"Timeframe"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor for the next page.","title":"Cursor"}},"required":["endpoint_id"],"title":"get_models_analyticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_workflows":{"post":{"operationId":"list_workflows","summary":"List your fal workflows with title, description, tags and the model endpoints they use. Use for \"Which fal workflows hav","description":"List your fal workflows with title, description, tags and the model endpoints they use. Use for \"Which fal workflows have I built\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search by workflow name or title.","title":"Search"},"used_endpoint_ids":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"default":null,"description":"Only workflows that use these endpoint ids, comma-separated.","title":"Used Endpoint Ids"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor for the next page.","title":"Cursor"}},"title":"list_workflowsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_serverless_apps":{"post":{"operationId":"list_serverless_apps","summary":"List your fal serverless apps with machine type, concurrency limits, timeouts, regions and last update. Use for \"Which f","description":"List your fal serverless apps with machine type, concurrency limits, timeouts, regions and last update. Use for \"Which fal serverless apps do I have deployed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Case-insensitive part of the app name.","title":"Search"},"environment":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Environment to list; the main environment by default.","title":"Environment"}},"title":"list_serverless_appsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_serverless_usage":{"post":{"operationId":"get_serverless_usage","summary":"Summarize the cost of your fal serverless apps over a time window by app and machine type. Needs a key with serverless a","description":"Summarize the cost of your fal serverless apps over a time window by app and machine type. Needs a key with serverless access. Use for \"How much did my fal serverless apps cost this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window, ISO 8601 date or time such as 2026-10-01. Defaults to 24 hours ago.","title":"Start"},"end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window (exclusive), ISO 8601. Defaults to now.","title":"End"},"app":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Only these app names, comma-separated.","title":"App"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Case-insensitive part of an app name.","title":"Search"},"expand":{"anyOf":[{"enum":["summary","time_series"],"type":"string"},{"type":"null"}],"default":"summary","description":"What to include: summary or time_series.","title":"Expand"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor for the next page.","title":"Cursor"}},"title":"get_serverless_usageArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_app_queue":{"post":{"operationId":"get_app_queue","summary":"Show how many requests are waiting in the queue of one of your fal serverless apps. Use for \"How long is the queue of my","description":"Show how many requests are waiting in the queue of one of your fal serverless apps. Use for \"How long is the queue of my fal app my-user/my-app\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"owner":{"description":"Username of the app owner.","maxLength":200,"title":"Owner","type":"string"},"name":{"description":"Serverless application name.","maxLength":200,"title":"Name","type":"string"}},"required":["owner","name"],"title":"get_app_queueArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_app_revisions":{"post":{"operationId":"list_app_revisions","summary":"List the deployed revisions of a fal serverless app with time, current flag, message and who deployed it. Use for \"What ","description":"List the deployed revisions of a fal serverless app with time, current flag, message and who deployed it. Use for \"What revisions of my fal app my-user/my-app were deployed recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"owner":{"description":"Username of the app owner.","maxLength":200,"title":"Owner","type":"string"},"name":{"description":"Serverless application name.","maxLength":200,"title":"Name","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many revisions to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor for the next page.","title":"Cursor"}},"required":["owner","name"],"title":"list_app_revisionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_compute_instances":{"post":{"operationId":"list_compute_instances","summary":"List your fal compute instances with type, region, IP address, status and creator. Use for \"Which fal compute instances ","description":"List your fal compute instances with type, region, IP address, status and creator. Use for \"Which fal compute instances are running\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor for the next page.","title":"Cursor"}},"title":"list_compute_instancesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_api_keys":{"post":{"operationId":"list_api_keys","summary":"List the API keys of the account with id, alias, preset, permissions and expiry. Key secrets are not returned. Needs an ","description":"List the API keys of the account with id, alias, preset, permissions and expiry. Key secrets are not returned. Needs an admin-level key. Use for \"Which API keys exist on my fal account and when do they expire\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor for the next page.","title":"Cursor"}},"title":"list_api_keysArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_account_billing":{"post":{"operationId":"get_account_billing","summary":"Show the account username and current credit balance. Needs a key on the BILLING preset or with billing permission. Use ","description":"Show the account username and current credit balance. Needs a key on the BILLING preset or with billing permission. Use for \"How many fal credits do I have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"expand":{"anyOf":[{"const":"credits","type":"string"},{"type":"null"}],"default":"credits","description":"Set to credits to include the current credit balance.","title":"Expand"}},"title":"get_account_billingArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}