Create a download URL for a specified file in Drive.
Drive is currently in Beta. API definitions, response structures, and behavior may change. Follow documentation updates and verify compatibility before production use.
POST /api/v1/forward/drives/download-url
Request Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer <PAT or SAT> |
| Content-Type | Yes | application/json |
| Idempotency-Key | No | Reuse the original value for retries of the same request. See Idempotent Retries. |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| identity_id | string | Yes | Identity ID within the current authentication scope; supply exactly once. An Identity-level SAT can select only its bound Identity. |
Request Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| path | string | Yes | Relative path of the file to download; cannot be the root or a directory. |
Path Rules
- Use a valid UTF-8 relative path such as
projects/reports. Absolute paths such as/projects/reportsorC:/projects/reportsare not accepted. - Separate directories with
/. Leading, trailing, or consecutive slashes, backslashes, and.or..path segments are not allowed. - Leading or trailing whitespace, control characters, and
%are not allowed, including escaped text such asprojects%2Freports.
Example Request
Example Response
HTTP 200 OK
Response Fields
| Field | Type | Description |
|---|---|---|
| url | string | Signed URL. |
| method | string | Always GET. |
| headers | object | Headers required when using the signed URL; {} if none are required. |
| expires_at | string | Expiration time in RFC 3339 format; valid for 15 minutes after issuance. |
| size | integer | File size in bytes; omitted when 0. |
| etag | string | File ETag; returned when nonempty. |
| content_type | string | File MIME type; returned when nonempty. |
Idempotent Retries
This endpoint optionally accepts Idempotency-Key. For retries, keep the authentication scope, Identity, key, and raw request body unchanged. Replayed responses include Idempotency-Replayed: true. To refresh a signed URL, omit this header or use a new value; replaying does not extend its validity.
Errors
| HTTP | Code | Condition |
|---|---|---|
| 400 | invalid_drive_path | The file path or Identity identifier format is invalid. |
| 400 | — | The request body is not valid JSON, contains incorrect field types, or includes unknown fields. |
| 400 | invalid_identity_id | identity_id is missing, empty, or supplied more than once. |
| 401 | — | Credentials are missing or invalid. Exchange a Service Account Key for a SAT first. |
| 403 | identity_mismatch | An Identity-level SAT selected another Identity. |
| 404 | drive_entry_not_found | The specified file does not exist. |
| 404 | identity_not_found | The Identity was not found within the current authentication scope. |
| 409 | idempotency_key_reused | The same key was used with a different request body. |
| 409 | idempotency_key_in_progress | A request with the same key is still processing. See Retry-After for the retry interval. |
| 413 | — | The request body exceeds the service limit. |
| 500 | — | Internal server error. |
| 503 | drive_unavailable | Drive storage, signing, or a dependency is temporarily unavailable. |
| 503 | idempotency_unavailable | Idempotency storage is temporarily unavailable. |
HTTP Error Response
Response Fields
| Field | Type | Description |
|---|---|---|
| type | string | Always error. |
| request_id | string | Request trace ID, returned when available. |
| error.type | string | Error category, such as invalid_request_error, authentication_error, permission_error, not_found_error, conflict_error, or api_error. |
| error.code | string | Business error code; omitted for some common errors. |
| error.message | string | Error description. |
error object, with the request trace ID in error.request_id. Storage service errors for signed URLs use a separate response format.
Gateway authentication errors may use a different response structure.