Skip to main content
Drives

Create an Upload URL

Create an upload URL for a target 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/upload-url

Request Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeYesapplication/json
Idempotency-KeyNoReuse the original value for retries of the same request. See Idempotent Retries.

Query Parameters

ParameterTypeRequiredDescription
identity_idstringYesIdentity ID within the current authentication scope; supply exactly once. An Identity-level SAT can select only its bound Identity.

Request Body Parameters

ParameterTypeRequiredDescription
pathstringYesRelative path of the target file; cannot be the root. Uploading to the same path overwrites existing content.
content_typestringNoFile MIME type: at most 255 bytes after trimming, a valid media type, and no control characters. Omitted or empty values impose no upload Content-Type constraint.

Path Rules

  • Use a valid UTF-8 relative path such as projects/reports. Absolute paths such as /projects/reports or C:/projects/reports are 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 as projects%2Freports.

Example Request

curl --silent --show-error --fail-with-body -X POST \
  "https://api.qoder.com/api/v1/forward/drives/upload-url?identity_id=idn_xxx" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "projects/readme.md",
    "content_type": "text/markdown"
  }'

Example Response

HTTP 200 OK 
{
  "url": "https://storage.example.com/signed-upload-url",
  "method": "PUT",
  "headers": {
    "Content-Type": "text/markdown"
  },
  "expires_at": "2026-09-07T02:15:00Z"
}

Response Fields

FieldTypeDescription
urlstringSigned URL.
methodstringAlways PUT.
headersobjectHeaders required when using the signed URL; {} if none are required.
expires_atstringExpiration time in RFC 3339 format; valid for 15 minutes after issuance.

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

HTTPCodeCondition
400invalid_drive_pathThe target file path or Identity identifier format is invalid.
400invalid_content_typeThe MIME type is invalid, exceeds 255 bytes, or contains control characters.
400—The request body is not valid JSON, contains incorrect field types, or includes unknown fields.
400invalid_identity_ididentity_id is missing, empty, or supplied more than once.
401—Credentials are missing or invalid. Exchange a Service Account Key for a SAT first.
403identity_mismatchAn Identity-level SAT selected another Identity.
404identity_not_foundThe Identity was not found within the current authentication scope.
409idempotency_key_reusedThe same key was used with a different request body.
409idempotency_key_in_progressA 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.
503drive_unavailableDrive storage, signing, or a dependency is temporarily unavailable.
503idempotency_unavailableIdempotency storage is temporarily unavailable.

HTTP Error Response

{
  "type": "error",
  "request_id": "req_xxx",
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_drive_path",
    "message": "Invalid Drive path."
  }
}

Response Fields

FieldTypeDescription
typestringAlways error.
request_idstringRequest trace ID, returned when available.
error.typestringError category, such as invalid_request_error, authentication_error, permission_error, not_found_error, conflict_error, or api_error.
error.codestringBusiness error code; omitted for some common errors.
error.messagestringError description.
Idempotency errors return only an 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.

List Directory Entries

Create a Download URL

First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference
Create an Upload URL - Qoder