Pre-upload a file - Relay

POST

/

v1

/

attachments

Pre-upload a file

curl --request POST \
  --url https://api.relayapp.im/v1/attachments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "<string>",
  "content_type": "<string>",
  "size_bytes": 52428800
}
'

{
  "attachment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "upload_url": "<string>",
  "download_url": "<string>",
  "http_method": "PUT",
  "expires_at": "2023-11-07T05:31:56Z",
  "required_headers": {}
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer token authentication. Include your API token in the Authorization header.

Format: Authorization: Bearer <your-token>

Body

application/json

filename

string

required

Name of the file to upload

Required string length: 1 - 255

content_type

string

required

MIME type of the file, as type/subtype. Relay accepts any file type and stores the bytes unchanged; the declared type is lowercased and returned to the reader as sent.

Maximum string length: 255

Pattern: ^[A-Za-z0-9!#$%&'*+.^_`|~-]+/[A-Za-z0-9!#$%&'*+.^_`|~-]+$

size_bytes

integer<int64>

required

Size of the file in bytes (max 100MB)

Required range: 1 <= x <= 104857600

duration_ms

integer | null

Audio or video duration in milliseconds when known. Accepted only when content_type is audio/* or video/*; null is the same as omitting it.

Required range: x >= 0

width

integer | null

Pixel width when known. Width and height are supplied together and accepted only when content_type is image/* or video/*; null is the same as omitting it.

Required range: x >= 1

height

integer | null

Pixel height when known. Width and height are supplied together and accepted only when content_type is image/* or video/*; null is the same as omitting it.

Required range: x >= 1

Response

Upload URL generated successfully

attachment_id

string<uuid>

required

Unique identifier for the attachment

upload_url

string<uri>

required

Opaque Relay upload URL. PUT the raw bytes with the exact required_headers before expires_at.

download_url

string<uri>

required

Opaque Relay download URL for the Attachment.

http_method

enum<string>

required

HTTP method to use for upload (always PUT)

Available options:

PUT

expires_at

string<date-time>

required

When the upload URL expires (15 minutes from now)

required_headers

object

required

Exact HTTP headers required by the upload URL.

Show child attributes

Pre-upload a file

curl --request POST \
  --url https://api.relayapp.im/v1/attachments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "<string>",
  "content_type": "<string>",
  "size_bytes": 52428800
}
'

{
  "attachment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "upload_url": "<string>",
  "download_url": "<string>",
  "http_method": "PUT",
  "expires_at": "2023-11-07T05:31:56Z",
  "required_headers": {}
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "trace_id": "<string>"
}