Upload an attachment

curl --request POST \
  --url https://api.blujay.io/v1/attachments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "photo.jpg",
  "content_type": "image/jpeg",
  "size_bytes": 428731
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({filename: 'photo.jpg', content_type: 'image/jpeg', size_bytes: 428731})
};

fetch('https://api.blujay.io/v1/attachments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.blujay.io/v1/attachments"

payload = {
    "filename": "photo.jpg",
    "content_type": "image/jpeg",
    "size_bytes": 428731
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

package main

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

func main() {

	url := "https://api.blujay.io/v1/attachments"

	payload := strings.NewReader("{\n  \"filename\": \"photo.jpg\",\n  \"content_type\": \"image/jpeg\",\n  \"size_bytes\": 428731\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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))

}

require 'uri'
require 'net/http'

url = URI("https://api.blujay.io/v1/attachments")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filename\": \"photo.jpg\",\n  \"content_type\": \"image/jpeg\",\n  \"size_bytes\": 428731\n}"

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blujay.io/v1/attachments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filename' => 'photo.jpg',
    'content_type' => 'image/jpeg',
    'size_bytes' => 428731
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "status": "success",
  "data": {
    "attachment_id": "att_abc123",
    "upload_url": "https://uploads.example.com/att_abc123?signature=8c1f0e2b",
    "upload_expires_at": "2026-10-14T17:16:00.000Z",
    "upload_headers": {
      "Content-Type": "image/jpeg",
      "Content-Length": "428731"
    },
    "download_url": "/v1/attachments/att_abc123/content"
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-14T17:01:00.000Z"
}

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "type": "validation",
    "http_status": 400,
    "retryable": false,
    "doc_url": "https://docs.blujay.io/errors/validation-error",
    "details": []
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-14T00:00:00.000Z"
}

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "<string>",
    "type": "validation",
    "http_status": 400,
    "retryable": true,
    "doc_url": "<string>",
    "details": [
      {}
    ],
    "retry_after": 2,
    "reset_at": "2026-10-14T17:01:00.000Z"
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-14T17:01:00.000Z",
  "client_request_id": "<string>"
}

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "<string>",
    "type": "validation",
    "http_status": 400,
    "retryable": true,
    "doc_url": "<string>",
    "details": [
      {}
    ],
    "retry_after": 2,
    "reset_at": "2026-10-14T17:01:00.000Z"
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-14T17:01:00.000Z",
  "client_request_id": "<string>"
}

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "<string>",
    "type": "validation",
    "http_status": 400,
    "retryable": true,
    "doc_url": "<string>",
    "details": [
      {}
    ],
    "retry_after": 2,
    "reset_at": "2026-10-14T17:01:00.000Z"
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-14T17:01:00.000Z",
  "client_request_id": "<string>"
}

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "<string>",
    "type": "validation",
    "http_status": 400,
    "retryable": true,
    "doc_url": "<string>",
    "details": [
      {}
    ],
    "retry_after": 2,
    "reset_at": "2026-10-14T17:01:00.000Z"
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-14T17:01:00.000Z",
  "client_request_id": "<string>"
}

Attachments

Upload an attachment

Starts an upload for a file you can reuse in messages. The response gives you an upload_url and upload_headers.

PUT the file’s raw bytes to upload_url with exactly the upload_headers returned. Don’t use multipart form data. The URL expires after 15 minutes.
Send the attachment_id in a media message part, or call GET /v1/attachments/{attachment_id} to check it.

There’s no separate “complete” call. Blujay checks the bytes the first time you read the attachment or send it, so the size and type must match what you declared. Files can be up to 100 MiB.

Attachment endpoints share a limit of 60 requests per minute per API key.

POST

attachments

Upload an attachment

curl --request POST \
  --url https://api.blujay.io/v1/attachments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "photo.jpg",
  "content_type": "image/jpeg",
  "size_bytes": 428731
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({filename: 'photo.jpg', content_type: 'image/jpeg', size_bytes: 428731})
};

fetch('https://api.blujay.io/v1/attachments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.blujay.io/v1/attachments"

payload = {
    "filename": "photo.jpg",
    "content_type": "image/jpeg",
    "size_bytes": 428731
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

package main

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

func main() {

	url := "https://api.blujay.io/v1/attachments"

	payload := strings.NewReader("{\n  \"filename\": \"photo.jpg\",\n  \"content_type\": \"image/jpeg\",\n  \"size_bytes\": 428731\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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))

}

require 'uri'
require 'net/http'

url = URI("https://api.blujay.io/v1/attachments")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filename\": \"photo.jpg\",\n  \"content_type\": \"image/jpeg\",\n  \"size_bytes\": 428731\n}"

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blujay.io/v1/attachments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filename' => 'photo.jpg',
    'content_type' => 'image/jpeg',
    'size_bytes' => 428731
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "status": "success",
  "data": {
    "attachment_id": "att_abc123",
    "upload_url": "https://uploads.example.com/att_abc123?signature=8c1f0e2b",
    "upload_expires_at": "2026-10-14T17:16:00.000Z",
    "upload_headers": {
      "Content-Type": "image/jpeg",
      "Content-Length": "428731"
    },
    "download_url": "/v1/attachments/att_abc123/content"
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-14T17:01:00.000Z"
}

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "type": "validation",
    "http_status": 400,
    "retryable": false,
    "doc_url": "https://docs.blujay.io/errors/validation-error",
    "details": []
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-14T00:00:00.000Z"
}

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "<string>",
    "type": "validation",
    "http_status": 400,
    "retryable": true,
    "doc_url": "<string>",
    "details": [
      {}
    ],
    "retry_after": 2,
    "reset_at": "2026-10-14T17:01:00.000Z"
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-14T17:01:00.000Z",
  "client_request_id": "<string>"
}

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "<string>",
    "type": "validation",
    "http_status": 400,
    "retryable": true,
    "doc_url": "<string>",
    "details": [
      {}
    ],
    "retry_after": 2,
    "reset_at": "2026-10-14T17:01:00.000Z"
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-14T17:01:00.000Z",
  "client_request_id": "<string>"
}

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "<string>",
    "type": "validation",
    "http_status": 400,
    "retryable": true,
    "doc_url": "<string>",
    "details": [
      {}
    ],
    "retry_after": 2,
    "reset_at": "2026-10-14T17:01:00.000Z"
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-14T17:01:00.000Z",
  "client_request_id": "<string>"
}

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "<string>",
    "type": "validation",
    "http_status": 400,
    "retryable": true,
    "doc_url": "<string>",
    "details": [
      {}
    ],
    "retry_after": 2,
    "reset_at": "2026-10-14T17:01:00.000Z"
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-14T17:01:00.000Z",
  "client_request_id": "<string>"
}

Authorizations

Authorization

string

header

required

Your workspace API key, sent as Authorization: Bearer blu_.... Workspace admins can find it in the Blujay app under API.

An API key has full access to your workspace and works on every endpoint. There is no test mode: every key sends real messages and changes real data, so keep it secret and use it only from your server.

Each API key can make 600 read requests and 120 write requests per minute, plus 60 attachment requests per minute. Over a limit you get 429 RATE_LIMIT_EXCEEDED with Retry-After.

Body

application/json

filename

string

required

The file name, without any folder path.

Required string length: 1 - 255

Example:

"receipt.jpg"

content_type

string

required

Lowercase MIME type without parameters, for example image/jpeg.

Maximum string length: 255

Pattern: ^[a-z0-9][a-z0-9!#$&^_.+-]*/[a-z0-9][a-z0-9!#$&^_.+-]*$

Example:

"image/jpeg"

size_bytes

integer

required

Required range: 1 <= x <= 104857600

Example:

284512

Response

The upload URL and headers for the new attachment.

Wraps every successful response. The result is in data.

status

enum<string>

required

Available options:

success

trace_id

string

required

Pattern: ^trc_[A-Za-z0-9_-]+$

Example:

"trc_8f2a1c0e4b7d"

timestamp

string<date-time>

required

Example:

"2026-10-14T17:01:00.000Z"

data

object

required

Show child attributes

client_request_id

string

Your X-Request-ID header value, echoed back when you send one. Not included on the send responses (POST /v1/chats, POST /v1/chats/{chat_id}/messages, POST /v1/messages/{message_id}/retry); keep your own mapping from your request ID to the returned message ID there.

Overview

Endpoints

Upload an attachment

Authorizations

Body

Response