Reserve a direct upload for a conversation

Reserves storage for a file and returns a one-time URL to PUT the bytes to. Two steps, not one:

POST here with the file’s name, size, MIME type and base64 MD5 checksum.
PUT the bytes to direct_upload.url with the headers it gives you. The upload is rejected if the bytes disagree with the size or checksum you declared.

Then send signed_id as the attachment when you create the message. Prefer POST /upload if you just want Tied to store a file for you — it takes the file directly and hands back a blob_id in one call. Direct upload exists so a large file can go straight to storage without passing through the application.

POST

api

accounts

{account_id}

conversations

{conversation_id}

direct_uploads

Reserve a direct upload for a conversation

curl --request POST \
  --url https://app.tied.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/direct_uploads \
  --header 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --data '
{
  "blob": {
    "filename": "orders.csv",
    "byte_size": 27,
    "checksum": "janaQDJaHWRN47FY/qJ9kQ==",
    "content_type": "text/csv"
  }
}
'

import requests

url = "https://app.tied.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/direct_uploads"

payload = { "blob": {
        "filename": "orders.csv",
        "byte_size": 27,
        "checksum": "janaQDJaHWRN47FY/qJ9kQ==",
        "content_type": "text/csv"
    } }
headers = {
    "api_access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {api_access_token: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    blob: {
      filename: 'orders.csv',
      byte_size: 27,
      checksum: 'janaQDJaHWRN47FY/qJ9kQ==',
      content_type: 'text/csv'
    }
  })
};

fetch('https://app.tied.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/direct_uploads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'

url = URI("https://app.tied.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/direct_uploads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api_access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"blob\": {\n    \"filename\": \"orders.csv\",\n    \"byte_size\": 27,\n    \"checksum\": \"janaQDJaHWRN47FY/qJ9kQ==\",\n    \"content_type\": \"text/csv\"\n  }\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.tied.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/direct_uploads"

	payload := strings.NewReader("{\n  \"blob\": {\n    \"filename\": \"orders.csv\",\n    \"byte_size\": 27,\n    \"checksum\": \"janaQDJaHWRN47FY/qJ9kQ==\",\n    \"content_type\": \"text/csv\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api_access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": 23,
  "key": "10jxqa9sxnw873rkmoutu49u0h4b",
  "filename": "orders.csv",
  "content_type": "text/csv",
  "metadata": {},
  "byte_size": 27,
  "checksum": "janaQDJaHWRN47FY/qJ9kQ==",
  "created_at": "2026-09-21T05:13:10.967Z",
  "service_name": "local",
  "attachable_sgid": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJalZuYVdRNkx5OWphR0YwZDI5dmRDOUJZM1JwZG1WVGRHOXlZV2RsT2pwQ2JHOWlMekl6UDJWNGNHbHlaWE5mYVc0R09nWkZWQT09IiwiZXhwIjpudWxsLCJwdXIiOiJhdHRhY2hhYmxlIn19--EXAMPLE",
  "signed_id": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBIQT09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--EXAMPLE",
  "direct_upload": {
    "url": "https://app.tied.com/rails/active_storage/blobs/proxy/EXAMPLE/asset.png",
    "headers": {
      "Content-Type": "text/csv"
    }
  }
}

{
  "error": "Resource could not be found"
}

{
  "error": "Resource could not be found"
}

{
  "message": "Url has already been taken",
  "attributes": [
    "url"
  ]
}

Authorizations

api_access_token

string

header

required

This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user.

Path Parameters

integer

required

The numeric ID of the account

conversation_id

integer

required

The numeric ID of the conversation

Body

application/json

blob

object

required

Describe the file before sending it. All four fields are required, and the subsequent PUT is rejected if the bytes disagree with byte_size or checksum.

Show child attributes

Response

Success

The stored blob plus the one-time URL to PUT the bytes to. This is Rails' ActiveStorage direct-upload response, passed through unchanged.

integer

The blob's numeric ID.

key

string

The storage key.

filename

string

The filename you declared.

content_type

string

The content type you declared.

byte_size

integer

The size you declared. The upload is rejected if the bytes do not match it.

checksum

string

The base64 MD5 you declared. The upload is rejected if the bytes do not match it.

metadata

object

Metadata ActiveStorage derives once the bytes arrive.

service_name

string

Which storage service holds it.

created_at

string

ISO-8601 timestamp.

signed_id

string

What you send as the attachment reference when creating the message.

attachable_sgid

string

Signed global ID for the blob, used by rich-text attachment flows.

direct_upload

object

Where and how to send the bytes.

Show child attributes

Reserve a direct upload for a conversation

curl --request POST \
  --url https://app.tied.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/direct_uploads \
  --header 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --data '
{
  "blob": {
    "filename": "orders.csv",
    "byte_size": 27,
    "checksum": "janaQDJaHWRN47FY/qJ9kQ==",
    "content_type": "text/csv"
  }
}
'

import requests

url = "https://app.tied.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/direct_uploads"

payload = { "blob": {
        "filename": "orders.csv",
        "byte_size": 27,
        "checksum": "janaQDJaHWRN47FY/qJ9kQ==",
        "content_type": "text/csv"
    } }
headers = {
    "api_access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {api_access_token: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    blob: {
      filename: 'orders.csv',
      byte_size: 27,
      checksum: 'janaQDJaHWRN47FY/qJ9kQ==',
      content_type: 'text/csv'
    }
  })
};

fetch('https://app.tied.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/direct_uploads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'

url = URI("https://app.tied.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/direct_uploads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api_access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"blob\": {\n    \"filename\": \"orders.csv\",\n    \"byte_size\": 27,\n    \"checksum\": \"janaQDJaHWRN47FY/qJ9kQ==\",\n    \"content_type\": \"text/csv\"\n  }\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.tied.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/direct_uploads"

	payload := strings.NewReader("{\n  \"blob\": {\n    \"filename\": \"orders.csv\",\n    \"byte_size\": 27,\n    \"checksum\": \"janaQDJaHWRN47FY/qJ9kQ==\",\n    \"content_type\": \"text/csv\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api_access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": 23,
  "key": "10jxqa9sxnw873rkmoutu49u0h4b",
  "filename": "orders.csv",
  "content_type": "text/csv",
  "metadata": {},
  "byte_size": 27,
  "checksum": "janaQDJaHWRN47FY/qJ9kQ==",
  "created_at": "2026-09-21T05:13:10.967Z",
  "service_name": "local",
  "attachable_sgid": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJalZuYVdRNkx5OWphR0YwZDI5dmRDOUJZM1JwZG1WVGRHOXlZV2RsT2pwQ2JHOWlMekl6UDJWNGNHbHlaWE5mYVc0R09nWkZWQT09IiwiZXhwIjpudWxsLCJwdXIiOiJhdHRhY2hhYmxlIn19--EXAMPLE",
  "signed_id": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBIQT09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--EXAMPLE",
  "direct_upload": {
    "url": "https://app.tied.com/rails/active_storage/blobs/proxy/EXAMPLE/asset.png",
    "headers": {
      "Content-Type": "text/csv"
    }
  }
}

{
  "error": "Resource could not be found"
}

{
  "error": "Resource could not be found"
}

{
  "message": "Url has already been taken",
  "attributes": [
    "url"
  ]
}

Getting started

Conversations

Contacts

Inboxes and channels

Automation and routing

Reporting

Help Center

Account and access

Billing

Client API

Widget API

Receiving webhooks

Reserve a direct upload for a conversation

Authorizations

Path Parameters

Body

Response