Forward API reference.
Description
Uploads file content and creates a File.
Path
POST /api/v1/forward/files
Request headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <PAT or SAT> |
Idempotency-Key | No | Optional idempotency key for create requests. The same key can only be reused for the same request. If omitted, local idempotent replay protection is not provided. |
Content-Type | Yes | multipart/form-data |
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
identity_id | string | No | Use only when operating on Identity-owned resources. A PAT can explicitly supply this query parameter; omitting it uses administrator scope. SAT ownership is determined by the credential. Explicitly supplying this parameter with any SAT (including an empty value) returns HTTP 400. See Identity ownership. |
Form fields
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | File content to upload. Maximum size: 500 MiB. See Supported upload file types. |
name | string | No | Display filename. Defaults to the multipart filename; after normalization it must be 1-255 bytes. |
metadata | JSON string | No | Metadata object. created_by is reserved and must not be supplied (supplying it returns 400). |
Example request
Example response
HTTP 201 Created
Response fields
| Field | Type | Description |
|---|---|---|
id | string | File ID. |
type | string | Always file. |
filename | string | Filename. |
size_bytes | integer | File size in bytes. |
mime_type | string | MIME type. |
created_at | string | Creation time in RFC 3339 format. |
updated_at | string | Last update time in RFC 3339 format. |
downloadable | boolean | Whether the File can be downloaded. |
scope | object/null | Resource scope associated with the File, such as a Session. |
metadata | object | File metadata. |
identity_id | string/null | Forward identity owner. |
Errors
| HTTP | Type | Trigger |
|---|---|---|
| 400 | invalid_request_error | The request body, path parameters, query parameters, or multipart fields are invalid; this includes explicitly supplying the query parameter identity_id with any SAT, even with an empty value. |
| 400 | invalid_request_error | The file content exceeds 500 MiB. |
| 400 | invalid_request_error | The file type is unsupported. See Supported upload file types. |
| 400 | invalid_request_error | If the reserved key created_by is supplied, message is metadata key "created_by" is reserved, identifying the invalid field. |
| 401 | authentication_error | The authentication token is missing or invalid. |
| 403 | permission_error | An Owner mismatch occurs in administrator scope, or a downstream service denies access. |
| 404 | not_found_error | The Identity specified by the PAT does not exist, is disabled or deleted, or does not belong to the caller. |
| 409 | conflict_error | The resource state, references, or idempotency key conflict. |
| 429 | rate_limit_error | Upload capacity is insufficient. |
| 500/502/503 | api_error | Forward or a dependent service failed. |