Forward API reference.
File object
Upload, get, and list endpoints return this structure.
| Field | Type | Description |
|---|---|---|
id | string | File ID with the file_ prefix |
type | string | Always "file" |
filename | string | Stored file name |
size_bytes | integer | File size in bytes |
mime_type | string | MIME type supplied during upload or detected from the filename |
downloadable | boolean | Whether the File can be downloaded through the /content endpoint |
scope | object | null | Scope when the File is attached to another resource, such as { "id": "sess_...", "type": "session" }; null when unattached |
metadata | object | Custom metadata supplied during upload; defaults to {} when omitted. created_by is reserved by Forward and must not be supplied by callers |
identity_id | string | null | Owning Forward identity; typically null when created with a PAT |
icon_url | string | null | Icon URL associated by Forward |
binding_info | Binding info | Binding information, such as Template reference counts |
created_at | string | Creation time in RFC 3339 format |
updated_at | string | Last update time in RFC 3339 format |
Supported upload file types
The upload endpoint accepts text-based files only.
| Category | Accepted values |
|---|---|
| MIME type | Any text/* MIME type, plus application/json, application/xml, application/javascript, application/x-yaml, and application/x-toml |
| Extension | .txt, .md, .csv, .json, .xml, .yaml, .yml, .toml, .ini, .conf, .cfg, .env, .log, .html, .htm, .css, .scss, .less, .js, .jsx, .ts, .tsx, .vue, .svelte, .py, .go, .rs, .java, .kt, .scala, .c, .cpp, .cc, .h, .hpp, .rb, .php, .swift, .r, .lua, .pl, .sh, .bash, .zsh, .fish, .ps1, .sql, .graphql, .gql, .proto, .dockerfile, .makefile, .gitignore, .editorconfig, .eslintrc, .prettierrc, .tex, .rst, .adoc, .org, .svg |
| Extensionless file name | dockerfile, makefile, gemfile, rakefile, procfile, vagrantfile, justfile, brewfile |
File download response object
The Download a File endpoint returns this structure, including a short-lived presigned URL.
| Field | Type | Description |
|---|---|---|
url | string | Presigned download URL |
expires_at | string | URL expiration time in RFC 3339 format |
filename | string | Suggested download filename, used for browser Content-Disposition |
Binding info
Reference summary included by Forward in File responses.
| Field | Type | Description |
|---|---|---|
agent_template_count | integer | Number of Templates currently bound to the File |
List pagination fields
| Field | Type | Description |
|---|---|---|
data | array of File objects | Records on the current page |
has_more | boolean | Whether another page is available |
next_page | string | null | Forward cursor for the next page (recommended). Equals the current page's last_id when has_more=true; otherwise null |
first_id | string | null | ID of the first record on the current page |
last_id | string | null | ID of the last record on the current page |
page, after_id, and before_id are mutually exclusive; providing more than one returns 400. Use page where possible; it has the same semantics as after_id.