Xeonr Developer Docs
UplApiUploads

Create upload

POST
/uplim.api.v1.BucketUploadsService/CreateUpload

Finalizes an upload after the file has been uploaded to the presigned URL. Supports creating new uploads, replacing existing ones, or upserting by path.

Authorization

OAuth2 upl:uploads:create
AuthorizationBearer <token>

OAuth 2.0 authorization

In: header

Scope: upl:uploads:create

Header Parameters

Connect-Protocol-Version?number

Define the version of the Connect protocol

Connect-Timeout-Ms?number

Define the timeout, in ms

Request Body

application/json

bucketRef?&

Reference to the bucket

uploadRequestId?string

Unique identifier for the upload request (RequestUploadResponse.upload_id)

Length1 <= length <= 128
filename?string

Name of the file to be uploaded

Lengthlength <= 4096
tags?tags

Tags to associate with the upload

Itemsitems <= 1000
uploadedBy?string

User who uploaded the file

Lengthlength <= 4096
partEtags?

List of part ETags for multipart uploads (S3 allows up to 10,000 parts)

Itemsitems <= 10000
allowAnyExtension?boolean

validate:skip a bool has no bounds

defaultSlugExtension?string|null
Lengthlength <= 1024
private?boolean|null

Private access for this upload. If null, inherits from parent folder. validate:skip a bool has no bounds

integrationHidden?boolean|null

Whether this upload is private to the owning integration. When true, only the owning integration (with API key if api_key_enabled) can access it. validate:skip a bool has no bounds

createdAt?google.protobuf.Timestamp|null

Optional creation timestamp. When set, overrides the default (now). Used by mobile photo sync to preserve the photo's original taken date.

lastSyncedAt?google.protobuf.Timestamp|nullDeprecated

DEPRECATED. Use last_synced_version instead. Kept only so in-flight old clients continue working through one rollout cycle. Timestamp comparison is vulnerable to server-clock skew and sub-second precision drift; version is clock-free.

lastSyncedVersion?integer

The Upload.version the caller observed on its last sync with the server. On a replace or upsert_path target: if the existing upload's current version is greater, the server detected a concurrent edit and will not overwrite the current content. The incoming bytes are stored as an UploadHistoryEntry with is_conflict = true, the unchanged current upload is returned, and CreateUploadResponse.conflict is set. The caller can retrieve the conflicting content via ListUploadHistory / GetUploadHistoryContent and reconcile however its product requires.

On a bare create target: behaves identically if an upload already exists at that (directory, slug); the existing upload is returned as current, and the caller's content is preserved as a conflict history entry. With no existing upload, creates normally.

Special case — if last_synced_version is set and the target no longer exists (deleted since the caller's last sync), the server resurrects the upload with the caller's content as the new current version (create semantics).

When 0 / unset, no conflict check is performed. Callers that don't care about cross-client concurrent edits (single-writer bots, bulk importers) can simply leave this unset.

Formatint32
Range0 <= value
metadata?|null

Arbitrary intent metadata to stamp on the created upload, mirroring CreateSignedUploadIntentRequest.metadata — the two upload paths now record intent identically. Surfaced back on Upload.intent_metadata and, more importantly, evaluated by content-type matchers via IntentMetadataMatch, so an app can declare what it is uploading ("type": "paste") instead of the matcher having to infer it from the filename or extension.

The whole struct is stored and returned, but only string-valued entries are visible to IntentMetadataMatch — a clause keyed on a number, bool, nested object or array never matches.

create?

Create a new upload in this directory

Response Body

application/json

application/json

curl -X POST "https://uploads-api.xeonr.io/uplim.api.v1.BucketUploadsService/CreateUpload" \  -H "Connect-Protocol-Version: 1" \  -H "Connect-Timeout-Ms: 1000" \  -H "Content-Type: application/json" \  -d '{}'
{
  "upload": {
    "uploadId": "string",
    "path": "string",
    "slug": "string",
    "url": "string",
    "contentUrl": "string",
    "sizeBytes": "string",
    "tags": [
      "string"
    ],
    "integrationId": "497a18ca-284e-40c0-985d-f72be35d468e",
    "integration": {
      "integrationId": "string",
      "name": "string",
      "oauthClientId": "string",
      "folderBehavior": "INTEGRATION_FOLDER_BEHAVIOR_UNSPECIFIED",
      "folderLinkUrl": "string",
      "mode": "INTEGRATION_MODE_UNSPECIFIED",
      "bucketLauncherEnabled": true
    },
    "allowAnyExtension": true,
    "defaultSlugExtension": "string",
    "generatedDescription": "string",
    "metaUploads": [
      {
        "type": {
          "name": "string",
          "n": 0,
          "filename": "string"
        },
        "metadataId": "string",
        "uploadUrl": "string",
        "downloadUrl": "string"
      }
    ],
    "private": true,
    "aliases": [
      {
        "aliasId": "string",
        "uploadId": "string",
        "path": "string",
        "slug": "string",
        "url": "string",
        "hasPassword": true,
        "expiresAt": "2023-01-15T01:30:15.01Z",
        "maxUses": 0,
        "useCount": 0,
        "allowedUserIds": [
          "string"
        ],
        "createdAt": "2023-01-15T01:30:15.01Z",
        "externalPath": "string"
      }
    ],
    "createdAt": "2023-01-15T01:30:15.01Z",
    "updatedAt": "2023-01-15T01:30:15.01Z",
    "author": {
      "userId": "string",
      "username": "string"
    },
    "lastModifiedBy": {
      "userId": "string",
      "username": "string"
    },
    "thumbnailGenerationVersion": 0,
    "aiDescriptionGenerationVersion": 0,
    "aiTagsGenerationVersion": 0,
    "virusScanGenerationVersion": 0,
    "aiDescriptionInputRef": "string",
    "intentMetadata": {
      "property1": {},
      "property2": {}
    },
    "externalPath": "string",
    "order": 0,
    "isVirtualFile": true,
    "integrationHidden": true,
    "version": 0,
    "thumbnailContentTypeUrn": "string",
    "thumbnailContentTypeIconName": "string",
    "thumbnailContentTypeIconUrl": "string",
    "metadataKvs": [
      {
        "key": "string",
        "valueType": "METADATA_VALUE_TYPE_UNSPECIFIED",
        "value": {
          "arrayValue": [
            {}
          ]
        },
        "title": "string",
        "iconName": "string",
        "hiddenFromUsers": true
      }
    ]
  },
  "conflict": true,
  "conflictHistory": {
    "historyId": "string",
    "uploadId": "string",
    "version": 0,
    "sizeBytes": "string",
    "replacedAt": "2023-01-15T01:30:15.01Z",
    "metaUploads": [
      {
        "type": {
          "name": "string",
          "n": 0,
          "filename": "string"
        },
        "metadataId": "string",
        "uploadUrl": "string",
        "downloadUrl": "string"
      }
    ],
    "author": {
      "userId": "string",
      "username": "string"
    },
    "isConflict": true
  }
}
{
  "code": "not_found",
  "message": "string",
  "details": [
    {
      "type": "string",
      "value": "string",
      "debug": {}
    }
  ]
}