/storage/buckets/{bucketName}/objectsUpload Object
Uploads one object into the bucket as multipart/form-data.
Fields:
file(the bytes).path(where the object goes in the bucket; it may contain slashes).- Optional
contentType. - Optional
upsert("true"replaces an object already at that path). - Optional
metadata, a flat JSON object of string values stored with the object.
Answers 201 with the stored object.
Needs upload rights on the bucket; in a custom bucket the bucket's storage policy decides, and replacing an existing object with upsert also needs the policy's delete grant.
The upload is audited as data.write.storage.object.created with the bucket, size and content type.
| bucketName * | path | The bucket's name. It is unique within the project. |
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| file * | string <binary> | The object's bytes. Its part's content type is used when |
| path * | string | Where the object goes in the bucket. It may contain slashes to group objects under a prefix. Example: "users/u_42/avatar.png" |
| contentType | string | The object's MIME type. Omitted, the The bucket's allowed MIME types apply to it. Example: "image/png" |
| upsert | "true" | "false" |
Omitted or any other value, an upload to a path that holds an object is refused. Example: "true" |
| metadata | string | A JSON object of string values stored with the object, sent as JSON text. Custom storage policies can read it as Example: "{\"owner\":\"u_42\",\"source\":\"profile-page\"}" |
| HTTP | K9O Code | Description |
|---|---|---|
| 201 | The object was written. | |
| 400 | K9O_INVALID_FIELD_VALUE | The object violates a bucket constraint (file-size limit, allowed MIME type, or metadata cap) or the metadata is malformed. |
| 401 | K9O_UNAUTHENTICATED | Authentication is required. |
| 403 | K9O_RBAC_DENY | The caller's project role does not permit this object operation. |
| 403 | K9O_ACCESS_DENIED | The bucket's storage policy does not allow upload for this caller (context.reason storage_policy_denied). Checked after the role and IAM checks; a bucket with no policy is unaffected. |
| 404 | K9O_BUCKET_NOT_FOUND | No bucket with this name exists in the project. |
| 409 | K9O_ALREADY_EXISTS | An object already exists at this path and upsert is false. |
| 422 | K9O_MALWARE_DETECTED | The uploaded object was quarantined by malware scanning and not stored. |
| data * | object | The stored object. |
| path * | string | The object's path in the bucket, as sent. Example: "users/u_42/avatar.png" |
| size * | integer | The object's size in bytes. Example: 48213 |
| lastModified * | string <date-time> | null | Null from the platform-managed and customer storage locations, which don't report a write time on upload. |
| meta * | any | Request metadata: cost, timing and correlation ids. |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.from('<collection>').upload()Showing example in TypeScript
{
"file": "string",
"path": "users/u_42/avatar.png",
"contentType": "image/png",
"upsert": "true",
"metadata": "{\"owner\":\"u_42\",\"source\":\"profile-page\"}"
}{
"data": {
"path": "users/u_42/avatar.png",
"size": 48213,
"lastModified": null
}
}