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, or null otherwise. 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 the 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 through parameters |
| SAT (bound to an Identity) | That Identity | Resolved automatically; cannot be switched through parameters |
identity_id is optional and is used only when operating on Identity-owned resources. A PAT can explicitly supply it; omitting it uses administrator scope. SAT ownership is determined by the credential. To operate in Identity scope, issue an Identity-scoped credential and do not explicitly supply this parameter (even with an empty value); otherwise, HTTP 400 is returned.
An 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
- In administrator scope (a PAT without
identity_idor an Admin SAT), Identity-owned Files are not visible. - An Identity cannot see Files owned by the account (or Workspace) itself or by other Identities under the same account.
- In a valid Identity scope, cross-scope get, download, or delete operations always return
404, without distinguishing between "not found" and "not yours". - A PAT without
identity_idand an Admin SAT retain existing behavior: an Owner mismatch returns403. A downstream permission check 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, getting, downloading, and deleting Files all support Identity scope.
GET /api/v1/forward/resources/batch does not support identity_id; its visibility rules are 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.