Falai/storage
fal.ai Storage — file ACLs, signed URLs, storage settings
2026.10.21.1
Changed: The README, the apiToken description and the missing-key error
now direct you to store the fal.ai API key in a vault
(swamp vault put falai API_KEY) and wire it with
--global-arg 'apiToken=${{ vault.get("falai", "API_KEY") }}'. The README
previously showed --global-arg apiToken=FAL_API_KEY, which invited passing the
key as a literal. The FAL_KEY environment variable is still read as a
fallback, but it is not redacted and is not recommended.
No method behavior changed. Stored resources need no migration.
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiToken? | string | fal.ai API key. Wire it with ${{ vault.get("falai", "API_KEY") }}; never pass the literal value. The FAL_KEY environment variable is read as a fallback, but it is not redacted and is not recommended. |
| Argument | Type | Description |
|---|---|---|
| url? | string | Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b/<id>/<filename>). Must not contain query parameters. |
| Argument | Type | Description |
|---|---|---|
| url? | string | Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b/<id>/<filename>). Must not contain query parameters. |
| default | enum | Fallback decision when no user-specific rule matches |
| rules? | array | User-specific overrides to the default decision |
| Argument | Type | Description |
|---|---|---|
| url? | string | Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b/<id>/<filename>). Must not contain query parameters. |
| expiration_seconds | number | How long the signed URL stays valid, in seconds (max 7 days) |
| Argument | Type | Description |
|---|---|---|
| expiration_duration_seconds? | number | Seconds after which newly uploaded files automatically expire and are deleted... |
| initial_acl? | object |
Resources
2026.10.14.1
Fixed: Methods that write a singleton resource failed on current swamp with
Data name 'latest' is reserved for internal use.
Changed: Singleton get and action methods now write their data under
storage_settings-current instead of latest. Anything that read
data.latest("<model>", "latest") or queried name == "latest" must use the
new name.
Upgrade note: Data previously stored under latest is not migrated; re-run
the method to populate the new name. No attribute schemas changed.
Added: The manifest now declares license: Apache-2.0 (SPDX). The registry quality rubric scores a declared license separately from the bundled LICENSE.md.
2026.09.18.1
Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the
repo. No behavioral changes in this extension.
2026.09.17.1
Response schema fields are now generated as optional/nullable-optional regardless of the spec's required list, so reading a resource stored under an older model version no longer throws Required when the live API adds a new required field. No API surface change for this extension.
2026.09.15.1
Changed: Bump zod 4.4.3 → 4.6.5
2026.09.10.4
Fixed:
- Resource instance names for get/update methods with two or more path
parameters (e.g.
get_app_queue_info(owner, name),get_workflow(username, workflow_name)) were built by joining raw values with"_". Two distinct owner/name pairs that split differently around an underscore (e.g."john"/"doe_app"and"john_doe"/"app") produced the identical instance name and collided. Multi-param instance names are now derived from a hash of the JSON-encoded parameter tuple, which delimits each part unambiguously.
Upgrade note: No schema changes. All fixes are internal to method execution; existing stored resources are unaffected.
2026.09.10.4
Fixed:
- Resource instance names for get/update methods with two or more path
parameters (e.g.
get_app_queue_info(owner, name),get_workflow(username, workflow_name)) were built by joining raw values with"_". Two distinct owner/name pairs that split differently around an underscore (e.g."john"/"doe_app"and"john_doe"/"app") produced the identical instance name and collided. Multi-param instance names are now derived from a hash of the JSON-encoded parameter tuple, which delimits each part unambiguously.
Upgrade note: No schema changes. All fixes are internal to method execution; existing stored resources are unaffected.
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned