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. Returns the Identity ID when owned by an Identity; otherwise null. See Identity ownership |
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 |
Identity ownership
An account (or Workspace) can have multiple Identities. Each Identity represents an end user of a product integrated with that account (or Workspace).
A File can belong to an account (or Workspace) or to an Identity. Ownership determines who can view, download, and delete the File.
Specifying ownership
| Caller | Ownership | How to specify |
|---|---|---|
| PAT | Account / Workspace | Omit identity_id (the default, unchanged from previous behavior) |
| PAT | Specified Identity | Supply the query parameter identity_id=<identity_id> |
| SAT (administrator) | Workspace | Resolved automatically; cannot be switched with a parameter |
| SAT (bound to an Identity) | That Identity | Resolved automatically; cannot be switched with a parameter |
identity_id is optional and is only used when operating on Identity-owned resources. A PAT can explicitly supply it; omitting it uses the administrator scope. For SATs, ownership is determined by the credential. To use Identity scope, issue an Identity-scoped credential and do not explicitly supply this parameter, even with an empty value. Any SAT, including Admin SAT, that supplies it receives HTTP 400.
The Identity specified by a PAT must belong to the account or Workspace represented by that PAT and must be enabled. An Identity that does not exist, is disabled or deleted, or does not belong to the caller returns 404.
Ownership isolation
- The administrator scope (a PAT without
identity_id, or an Admin SAT) cannot see Identity-owned Files. - An Identity cannot see Files owned by the account (or Workspace) itself or by other Identities in the same account.
- Within a valid Identity scope, cross-scope attempts to retrieve, download, or delete resources all return
404, without distinguishing between nonexistent resources and resources owned by someone else. - PATs without
identity_idand Admin SATs retain the existing behavior: an owner mismatch returns403. Downstream permission checks may also return403. - Creation idempotency keys are isolated by ownership. Different Identities can reuse the same
Idempotency-Keywithout replaying each other's requests.
Supported endpoints
Uploading, searching, listing, retrieving, downloading, and deleting Files all support Identity scope.
GET /api/v1/forward/resources/batch does not support identity_id; its visibility rules remain unchanged.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.