--- title: "POST /api/attachments:upload" method: POST path: "/api/attachments:upload" tags: ["AttachmentService"] --- # POST /api/attachments:upload `POST /api/attachments:upload` ## Request - The document declares no server URL. - Auth: none declared UploadAttachment uploads a file in bounded chunks. The first call carries the spec and returns an upload_id; later calls carry that upload_id. Uploads are bound to the authenticated user, expire after 30 minutes of inactivity, and do not survive a server restart. ## Request body - UploadAttachmentRequest: Request message for AttachmentService.UploadAttachment. - `spec` UploadAttachmentSpec: UploadAttachmentSpec describes the attachment that a new upload creates. - `attachment` Attachment, required: Attachment is a file uploaded by a user, optionally linked to a memo. - `name` string: Identifier. The resource name of the attachment. Format: attachments/{attachment} - `creator` string: Output only. The user who uploaded the attachment, which may differ from the creator of the linked memo. Format: users/{user} - `filename` string, required: Required. The filename of the attachment. - `type` string, required: Required. The MIME type of the attachment. If empty on create, the service detects it from the filename and content. - `content` string, bytes: Input only. The content of the attachment. - `externalLink` string: Optional. The external link of the attachment. Set only for externally stored attachments; ignored on create. - `motionMedia` MotionMedia: MotionMedia links the parts of a motion photo. - `family` 'MOTION_MEDIA_FAMILY_UNSPECIFIED' | 'APPLE_LIVE_PHOTO' | 'ANDROID_MOTION_PHOTO', enum: The motion photo format. - `role` 'MOTION_MEDIA_ROLE_UNSPECIFIED' | 'STILL' | 'VIDEO' | 'CONTAINER', enum: The part this attachment plays in the motion photo. - `groupId` string: Groups the attachments that belong to one motion photo. Required for client-supplied Apple Live Photo metadata; for an Android motion photo it is the attachment's own ID. - `presentationTimestampUs` string: Presentation timestamp of the still frame within the video, in microseconds. - `hasEmbeddedVideo` boolean: Whether the file embeds the motion video, as in an Android motion photo container. - `mediaMetadata` MediaMetadata: MediaMetadata contains normalized metadata explicitly supplied by a client. The service validates and stores this data but does not extract it from the media file. - `width` integer: Display-oriented width in pixels. Must be provided with height. - `height` integer: Display-oriented height in pixels. Must be provided with width. - `photo` PhotoMetadata: PhotoMetadata is metadata recorded by the source of a photo. - `captureTime` MediaCaptureTime: MediaCaptureTime is the local time at which media was captured. - `localDateTime` string: Local date and time without a time zone, formatted as YYYY-MM-DDTHH:mm:ss[.fraction]. - `utcOffset` string: UTC offset formatted as Z or +/-HH:MM. - `location` MediaLocation: MediaLocation is the geographic location at which media was captured. - `latitude` number, double: WGS84 latitude in decimal degrees. Must be provided with longitude. - `longitude` number, double: WGS84 longitude in decimal degrees. Must be provided with latitude. - `altitudeMeters` number, double: Signed altitude in meters relative to sea level. - `sourceExifOrientation` integer: EXIF orientation value from 1 through 8 as recorded by the source file. This value is informational and must not be reapplied to the stored attachment; width and height already describe its display-oriented dimensions. - `cameraMake` string: The camera manufacturer. - `cameraModel` string: The camera model. - `lensModel` string: The lens model. - `fNumber` number, double: The aperture f-number. - `exposureTimeSeconds` number, double: The exposure time in seconds. - `iso` integer: The ISO sensitivity. - `focalLengthMm` number, double: The focal length in millimeters. - `video` VideoMetadata: VideoMetadata is metadata recorded by the source of a video. - `durationSeconds` number, double: The duration of the video in seconds. - `memo` string: Optional. The memo the attachment is linked to. On create, the caller must be able to manage the memo. Format: memos/{memo} - `size` string: Output only. The size of the stored content in bytes. - `createTime` string, date-time: Output only. The creation time. - `attachmentId` string: Optional. The ID to use for the attachment. If empty, a unique ID is generated. Format: ^[a-zA-Z0-9]([a-zA-Z0-9-]{0,34}[a-zA-Z0-9])?$ - `totalSize` string: Optional. Total size of the file in bytes before media processing. Zero represents an empty file. - `uploadId` string: Continues the upload identified by a previous response. - `writeOffset` string, required: Required. Zero-based byte offset at which data is written. Must equal the committed size, except when retrying the most recently accepted chunk with identical bytes and offset, which is accepted without writing again. - `data` string, bytes: Optional. File bytes, at most max_chunk_size long. With no data and finish_write false, the call reports progress without writing, and write_offset is ignored. - `finishWrite` boolean: Optional. Finalize the upload after writing data. The committed size must then equal total_size. Any later call for the same upload_id returns the created attachment. ## Response `200` OK - UploadAttachmentResponse: Response message for AttachmentService.UploadAttachment. - `uploadId` string: Opaque ID for subsequent calls. This is not a resource name. - `committedSize` string: Number of file bytes committed so far. - `maxChunkSize` integer: Maximum number of data bytes accepted in one call. - `attachment` Attachment: Attachment is a file uploaded by a user, optionally linked to a memo. - `name` string: Identifier. The resource name of the attachment. Format: attachments/{attachment} - `creator` string: Output only. The user who uploaded the attachment, which may differ from the creator of the linked memo. Format: users/{user} - `filename` string, required: Required. The filename of the attachment. - `type` string, required: Required. The MIME type of the attachment. If empty on create, the service detects it from the filename and content. - `content` string, bytes: Input only. The content of the attachment. - `externalLink` string: Optional. The external link of the attachment. Set only for externally stored attachments; ignored on create. - `motionMedia` MotionMedia: MotionMedia links the parts of a motion photo. - `family` 'MOTION_MEDIA_FAMILY_UNSPECIFIED' | 'APPLE_LIVE_PHOTO' | 'ANDROID_MOTION_PHOTO', enum: The motion photo format. - `role` 'MOTION_MEDIA_ROLE_UNSPECIFIED' | 'STILL' | 'VIDEO' | 'CONTAINER', enum: The part this attachment plays in the motion photo. - `groupId` string: Groups the attachments that belong to one motion photo. Required for client-supplied Apple Live Photo metadata; for an Android motion photo it is the attachment's own ID. - `presentationTimestampUs` string: Presentation timestamp of the still frame within the video, in microseconds. - `hasEmbeddedVideo` boolean: Whether the file embeds the motion video, as in an Android motion photo container. - `mediaMetadata` MediaMetadata: MediaMetadata contains normalized metadata explicitly supplied by a client. The service validates and stores this data but does not extract it from the media file. - `width` integer: Display-oriented width in pixels. Must be provided with height. - `height` integer: Display-oriented height in pixels. Must be provided with width. - `photo` PhotoMetadata: PhotoMetadata is metadata recorded by the source of a photo. - `captureTime` MediaCaptureTime: MediaCaptureTime is the local time at which media was captured. - `localDateTime` string: Local date and time without a time zone, formatted as YYYY-MM-DDTHH:mm:ss[.fraction]. - `utcOffset` string: UTC offset formatted as Z or +/-HH:MM. - `location` MediaLocation: MediaLocation is the geographic location at which media was captured. - `latitude` number, double: WGS84 latitude in decimal degrees. Must be provided with longitude. - `longitude` number, double: WGS84 longitude in decimal degrees. Must be provided with latitude. - `altitudeMeters` number, double: Signed altitude in meters relative to sea level. - `sourceExifOrientation` integer: EXIF orientation value from 1 through 8 as recorded by the source file. This value is informational and must not be reapplied to the stored attachment; width and height already describe its display-oriented dimensions. - `cameraMake` string: The camera manufacturer. - `cameraModel` string: The camera model. - `lensModel` string: The lens model. - `fNumber` number, double: The aperture f-number. - `exposureTimeSeconds` number, double: The exposure time in seconds. - `iso` integer: The ISO sensitivity. - `focalLengthMm` number, double: The focal length in millimeters. - `video` VideoMetadata: VideoMetadata is metadata recorded by the source of a video. - `durationSeconds` number, double: The duration of the video in seconds. - `memo` string: Optional. The memo the attachment is linked to. On create, the caller must be able to manage the memo. Format: memos/{memo} - `size` string: Output only. The size of the stored content in bytes. - `createTime` string, date-time: Output only. The creation time. ## Other responses - `default`: Default error response ## Changes - **2026-10-08** `1846a777b0ef`: 1 info - endpoint added [Operation history](https://skmtc.dev/usememos/apis/untitled-api/changes/api/attachments:upload/post.md) --- [API](https://skmtc.dev/usememos/apis/untitled-api.md) - [All operations](https://skmtc.dev/usememos/apis/untitled-api/llms.txt) - [OpenAPI document](https://skmtc.dev/usememos/apis/untitled-api/revisions/f587355e35b4?raw)