Forward API リファレンス。
File object
Upload, get, and list endpoints return this structure.
| フィールド | 型 | 説明 |
|---|---|---|
id | string | file_ プレフィックス付きの File ID |
type | string | Always "file" |
filename | string | 保存されたファイル名 |
size_bytes | integer | ファイルサイズ（バイト） |
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
アップロードエンドポイントはテキストベースのファイルのみを受け付けます。
| カテゴリ | 受け入れ可能な値 |
|---|---|
| MIME タイプ | すべての text/* MIME タイプに加え、application/json、application/xml、application/javascript、application/x-yaml、application/x-toml |
| 拡張子 | .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 |
| 拡張子なしファイル名 | 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.
| フィールド | 型 | 説明 |
|---|---|---|
url | string | 署名付きダウンロード 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.
| フィールド | 型 | 説明 |
|---|---|---|
agent_template_count | integer | Number of Templates currently bound to the File |
List pagination fields
| フィールド | 型 | 説明 |
|---|---|---|
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.