# Upload API An *Upload* is a temporary resource you create by uploading a file. It is the first step before creating a *Media*: when you upload a file, the response returns a single *Upload*, and you use this *Upload*'s information to create a *Media*. Creating a *Media* happens on CMA (Weegloo User) or ACMA (Service User) and is outside the scope of this page. An *Upload* is a temporary resource. It expires 24 hours after creation (`expiresAt`), and if you do not turn it into a *Media* within that window, it disappears. An *Upload* has no concept of publishing or versioning (no `version`, `status`, or `publish` properties). It also has no body fields, and carries only the system property `sys`. The base URL is `https://upload.weegloo.com/v1`, and every request requires a Bearer token that authenticates against Upload. ## Resource structure {#resource-structure} The following is the response for an *Upload* created by uploading a clothing-store product photo (a tumbler image) to a *Space*. It has only `sys`, which contains keys such as `owner`, `expiresAt`, and `size`. ```json { "sys": { "id": "4bgMfu7cFGYDRQn4jdqFICdQiCZ15W", "type": "Upload", "owner": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } }, "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-18T04:51:53.903Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "updatedAt": "2026-06-18T04:51:53.903Z", "expiresAt": "2026-06-19T04:51:53.903Z", "size": 50847 } } ``` Key properties: - `sys.id`: The unique identifier of the *Upload*. You pass this value when creating a *Media*. It also goes into `{uploadId}` in the single-read and delete paths. - `sys.owner`: A reference pointing to where this *Upload* belongs. Its `targetType` is `Space` or `Organization` (see [Space and Organization contexts](#space-and-organization-contexts) below). - `sys.expiresAt`: The expiration time. It is 24 hours after `createdAt`, and once this time passes the *Upload* disappears. - `sys.size`: The size of the uploaded file (in bytes). The example above is `50847` bytes. ## System properties (sys) {#system-properties-sys} Every *Upload* carries its system properties in the `sys` object. `owner`, `createdBy`, and `updatedBy` are in the `Refer` shape (`{ "sys": { "id", "type": "Refer", "targetType" } }`). | Property | Type | Description | |---|---|---| | `id` | string | Unique resource identifier. | | `type` | string | Resource kind. For an *Upload* this is always `"Upload"`. | | `owner` | Refer | Where this *Upload* belongs. Its `targetType` is `Space` or `Organization`. | | `createdBy` | Refer<User> | The user who created it. | | `createdAt` | string (date-time) | Creation time. | | `updatedBy` | Refer<User> | The user who last updated it. | | `updatedAt` | string (date-time) | Last update time. | | `expiresAt` | string (date-time) | The expiration time. It is 24 hours after `createdAt`, and once it passes the *Upload* disappears. | | `size` | integer (int64) | The size of the uploaded file (in bytes). | All 9 properties above are always included in the response. The `version`, `status`, and `publish` found in the `sys` of a *Content* or *Content Type* are not present in an *Upload*. That is because an *Upload* is not a resource that is published or versioned, but a one-time ingredient for creating a *Media*. Unlike the `space` of other resources, which points to a single kind, `owner` points to a `Space` or an `Organization` depending on `targetType`. ## Space and Organization contexts {#space-and-organization-contexts} An *Upload* can be created in two contexts, and the path and `sys.owner` differ by context. | Context | Path basis | `sys.owner.sys.targetType` | Use | |---|---|---|---| | *Space* | `/spaces/{spaceId}/uploads` | `Space` | A file that will become the ingredient of a *Media*, such as a product photo. | | *Organization* | `/organizations/{organizationId}/uploads` | `Organization` | An organization-level asset such as an organization icon. | An *Upload* in the *Space* context is the ingredient for creating a *Media* in that *Space*. An *Upload* in the *Organization* context is used when you upload a file that is used directly by the organization, such as an organization icon. In both cases the resource structure returned in the response is the same; only the `targetType` value of `sys.owner` differs. ## Upload methods: multipart and binary {#upload-methods-multipart-and-binary} There are two methods for the POST request that uploads a file. Either way, what comes back in the response is the same *Upload* resource. The **multipart method** sends the request body as `multipart/form-data`. The file goes into a form field named `file`. It suits situations where you send form data, such as uploading directly from a browser's file-picker input. The **binary method** puts the raw bytes of the file directly into the request body. There is no restriction on the body's media type (`Content-Type`) (usually `application/octet-stream` is used), and in the *Space* context you must also send the byte length of the body in the `Content-Length` header. It suits server-side code that transmits only the file bytes without a form structure. ## API {#api} The base URL for all endpoints below is `https://upload.weegloo.com/v1`, and a Bearer token that authenticates against Upload is required in the `Authorization` header. The 4 endpoints for the *Space* context come first, followed by the 4 for the *Organization* context. ```api-endpoint { "title": "Create a Space Upload (multipart)", "method": "POST", "path": "/spaces/{spaceId}/uploads/multipart", "description": "Creates an Upload by uploading a file to a Space as multipart/form-data. The file goes into a form field named file. On success it returns the Upload resource with 201.", "responseStatus": 201, "baseUrl": "https://upload.weegloo.com/v1", "pathParameterSchema": { "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true } }, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (Upload authentication)" } }, "requestContentType": "multipart/form-data", "requestBodySchema": { "type": "object", "required": ["file"], "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload" } } }, "responseExample": { "sys": { "id": "4bgMfu7cFGYDRQn4jdqFICdQiCZ15W", "type": "Upload", "owner": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } }, "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-18T04:51:53.903Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "updatedAt": "2026-06-18T04:51:53.903Z", "expiresAt": "2026-06-19T04:51:53.903Z", "size": 50847 } } } ``` ```api-endpoint { "title": "Create a Space Upload (binary)", "method": "POST", "path": "/spaces/{spaceId}/uploads", "description": "Creates an Upload by putting the raw bytes of a file directly into the body of a request to a Space. You must also send the byte length of the body in the Content-Length header. On success it returns the Upload resource with 201.", "responseStatus": 201, "baseUrl": "https://upload.weegloo.com/v1", "pathParameterSchema": { "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true } }, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (Upload authentication)" }, "Content-Length": { "type": "integer", "description": "The byte length of the request body", "required": true } }, "requestContentType": "application/octet-stream", "requestBodySchema": { "type": "string", "format": "binary", "description": "Raw file bytes" }, "responseExample": { "sys": { "id": "4bgMfu7cFGYDRQn4jdqFICdQiCZ15W", "type": "Upload", "owner": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } }, "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-18T04:51:53.903Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "updatedAt": "2026-06-18T04:51:53.903Z", "expiresAt": "2026-06-19T04:51:53.903Z", "size": 50847 } } } ``` ```api-endpoint { "title": "Read a single Space Upload", "method": "GET", "path": "/spaces/{spaceId}/uploads/{uploadId}", "description": "Reads one Upload in a Space by sys.id. An expired Upload can no longer be read.", "responseStatus": 200, "baseUrl": "https://upload.weegloo.com/v1", "pathParameterSchema": { "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true }, "uploadId": { "type": "string", "description": "The sys.id of the Upload", "required": true } }, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (Upload authentication)" } }, "responseExample": { "sys": { "id": "4bgMfu7cFGYDRQn4jdqFICdQiCZ15W", "type": "Upload", "owner": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } }, "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-18T04:51:53.903Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "updatedAt": "2026-06-18T04:51:53.903Z", "expiresAt": "2026-06-19T04:51:53.903Z", "size": 50847 } } } ``` ```api-endpoint { "title": "Delete a Space Upload", "method": "DELETE", "path": "/spaces/{spaceId}/uploads/{uploadId}", "description": "Deletes one Upload in a Space. On success it responds with 204 No Content and no response body.", "responseStatus": 204, "baseUrl": "https://upload.weegloo.com/v1", "pathParameterSchema": { "spaceId": { "type": "string", "description": "The sys.id of the Space", "required": true }, "uploadId": { "type": "string", "description": "The sys.id of the Upload", "required": true } }, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (Upload authentication)" } } } ``` ```api-endpoint { "title": "Create an Organization Upload (multipart)", "method": "POST", "path": "/organizations/{organizationId}/uploads/multipart", "description": "Creates an Upload by uploading a file to an Organization as multipart/form-data. The file goes into a form field named file. On success it returns the Upload resource with 201.", "responseStatus": 201, "baseUrl": "https://upload.weegloo.com/v1", "pathParameterSchema": { "organizationId": { "type": "string", "description": "The sys.id of the Organization", "required": true } }, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (Upload authentication)" } }, "requestContentType": "multipart/form-data", "requestBodySchema": { "type": "object", "required": ["file"], "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload" } } }, "responseExample": { "sys": { "id": "4bgMfu7cFGYDRQn4jdqFIA1gaqmAS1", "type": "Upload", "owner": { "sys": { "id": "ilLRJxDp", "type": "Refer", "targetType": "Organization" } }, "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-18T04:49:41.234Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "updatedAt": "2026-06-18T04:49:41.234Z", "expiresAt": "2026-06-19T04:49:41.234Z", "size": 50847 } } } ``` ```api-endpoint { "title": "Create an Organization Upload (binary)", "method": "POST", "path": "/organizations/{organizationId}/uploads", "description": "Creates an Upload by putting the raw bytes of a file directly into the body of a request to an Organization. On success it returns the Upload resource with 201.", "responseStatus": 201, "baseUrl": "https://upload.weegloo.com/v1", "pathParameterSchema": { "organizationId": { "type": "string", "description": "The sys.id of the Organization", "required": true } }, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (Upload authentication)" } }, "requestContentType": "application/octet-stream", "requestBodySchema": { "type": "string", "format": "binary", "description": "Raw file bytes" }, "responseExample": { "sys": { "id": "4bgMfu7cFGYDRQn4jdqFIA1gaqmAS1", "type": "Upload", "owner": { "sys": { "id": "ilLRJxDp", "type": "Refer", "targetType": "Organization" } }, "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-18T04:49:41.234Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "updatedAt": "2026-06-18T04:49:41.234Z", "expiresAt": "2026-06-19T04:49:41.234Z", "size": 50847 } } } ``` ```api-endpoint { "title": "Read a single Organization Upload", "method": "GET", "path": "/organizations/{organizationId}/uploads/{uploadId}", "description": "Reads one Upload in an Organization by sys.id. An expired Upload can no longer be read.", "responseStatus": 200, "baseUrl": "https://upload.weegloo.com/v1", "pathParameterSchema": { "organizationId": { "type": "string", "description": "The sys.id of the Organization", "required": true }, "uploadId": { "type": "string", "description": "The sys.id of the Upload", "required": true } }, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (Upload authentication)" } }, "responseExample": { "sys": { "id": "4bgMfu7cFGYDRQn4jdqFIA1gaqmAS1", "type": "Upload", "owner": { "sys": { "id": "ilLRJxDp", "type": "Refer", "targetType": "Organization" } }, "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "createdAt": "2026-06-18T04:49:41.234Z", "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }, "updatedAt": "2026-06-18T04:49:41.234Z", "expiresAt": "2026-06-19T04:49:41.234Z", "size": 50847 } } } ``` ```api-endpoint { "title": "Delete an Organization Upload", "method": "DELETE", "path": "/organizations/{organizationId}/uploads/{uploadId}", "description": "Deletes one Upload in an Organization. On success it responds with 204 No Content and no response body.", "responseStatus": 204, "baseUrl": "https://upload.weegloo.com/v1", "pathParameterSchema": { "organizationId": { "type": "string", "description": "The sys.id of the Organization", "required": true }, "uploadId": { "type": "string", "description": "The sys.id of the Upload", "required": true } }, "requestHeaderSchema": { "Authorization": { "type": "string", "description": "Bearer token (Upload authentication)" } } } ``` ## Related documents {#related-documents} - [Media](/api/reference/cma/media.md): The request format for creating a *Media* from an uploaded Upload. - [Media (concept)](/getting-started/core-concepts/content/media.md): How to work with file assets in the content studio.