Create Attachment Upload URL

Beta

POST/v1/messaging/conversations/{id}/attachments/actions/upload-url

Idempotent with Idempotency-Key header. Learn more

Mints a presigned URL for uploading a chat attachment directly to object storage.

Permissions requiredValues:messaging:create

The role behind your API key or agent must grant every one of these permissions.

idstring

Conversation ID the attachment will be sent in.

include[]optional arrayenumValues:attachmentattachment.resource

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

filenamestring

The original filename of the file to upload.

content_typeoptional string

The MIME content type of the file (sent as the Content-Type on the upload).

objectstringenumValues:attachment_upload_target

Resource type identifier.

attachmentmessage_attachmentExpandablenullable

Pre-allocated attachment metadata for the staged upload.

idstring

Attachment ID.

objectstringenumValues:message_attachment

Resource type identifier.

kindstringenumValues:fileimagelink

The kind of attachment, which determines how it is stored and which of the fields below are populated.

file: an uploaded non-image file.
image: an uploaded image.
link: an external URL reference, with no stored file.
resource: a reference to an in-app resource, such as an order.

filenamestringnullable

The original filename for uploaded attachments.

null for link/resource attachments.

content_typestringnullable

The MIME content type for uploaded attachments.

null for link/resource attachments.

size_bytesintegernullable

The size in bytes for uploaded attachments.

null when unknown or for link/resource attachments.

urlstringnullable

A time-limited download URL for uploaded (file/image) attachments, or the link URL.

null for resource attachments.

resourceentityExpandablenullable

The linked in-app resource for resource attachments.

null for file/image/link attachments.

idstring

Unique identifier for the entity.

objectstringenumValues:entity

Resource type identifier.

typestringenumValues:accountactorentity

The resource kind that this entity references, as an object-type value (e.g. user, account).

Unlike object — which is always entity — this names the underlying resource the id points to.

namestringnullable

Human-readable display name for the entity (e.g. a user's full name, a sales order number).

handlestringnullable

Secondary human-readable identifier (e.g. email address, username, redacted API key value).

created_atstring (date-time)

Creation timestamp.

upload_urlstring

The presigned URL to PUT the file to.

s3_keystring

The object-storage key to echo back when sending the message.

expires_atstring (date-time)

When the upload URL expires.

Responses

200

Successful response for Create Attachment Upload URL

Create Attachment Upload URL

import Augno from '@augno/sdk';

const client = new Augno({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const attachmentUploadTarget = await client.messaging.conversations.attachments.actions.uploadURL(
  'cv_01h9z8q1w2e3r4t5y6u7i8cv',
  { filename: 'diagram.png', content_type: 'image/png' },
);

console.log(attachmentUploadTarget.attachment);

import Augno from '@augno/sdk';

const client = new Augno({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const attachmentUploadTarget = await client.messaging.conversations.attachments.actions.uploadURL(
  'cv_01h9z8q1w2e3r4t5y6u7i8cv',
  { filename: 'diagram.png', content_type: 'image/png' },
);

console.log(attachmentUploadTarget.attachment);

200 example

{
  "object": "attachment_upload_target",
  "attachment": {
    "id": "mgah_01h9z8q1w2e3r4t5y6u7mgah",
    "object": "message_attachment",
    "kind": "image",
    "filename": "diagram.png",
    "content_type": "image/png",
    "size_bytes": 48213,
    "url": "https://chat-bucket.s3.amazonaws.com/chat/ac/cv/mgah/diagram.png?X-Amz-Signature=...",
    "resource": null,
    "created_at": "2026-05-10T00:00:00Z"
  },
  "upload_url": "https://chat-bucket.s3.amazonaws.com/staged/ac/cv/mgah/diagram.png?X-Amz-Signature=...",
  "s3_key": "staged/ac_01h9z8q1w2e3r4t5y6u7i8o9/cv_01h9z8q1w2e3r4t5y6u7i8cv/mgah_01h9z8q1w2e3r4t5y6u7mgah/diagram.png",
  "expires_at": "2026-05-10T00:23:00Z"
}

{
  "object": "attachment_upload_target",
  "attachment": {
    "id": "mgah_01h9z8q1w2e3r4t5y6u7mgah",
    "object": "message_attachment",
    "kind": "image",
    "filename": "diagram.png",
    "content_type": "image/png",
    "size_bytes": 48213,
    "url": "https://chat-bucket.s3.amazonaws.com/chat/ac/cv/mgah/diagram.png?X-Amz-Signature=...",
    "resource": null,
    "created_at": "2026-05-10T00:00:00Z"
  },
  "upload_url": "https://chat-bucket.s3.amazonaws.com/staged/ac/cv/mgah/diagram.png?X-Amz-Signature=...",
  "s3_key": "staged/ac_01h9z8q1w2e3r4t5y6u7i8o9/cv_01h9z8q1w2e3r4t5y6u7i8cv/mgah_01h9z8q1w2e3r4t5y6u7mgah/diagram.png",
  "expires_at": "2026-05-10T00:23:00Z"
}

Create Attachment Upload URL

Authorization

Path Parameters

Query Parameters

Request Body

Returns

Responses