Skip to main content
POST
/
attachments
Upload Attachments
curl --request POST \
  --url https://connect.penbox.io/v1/attachments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "data": "aSDinaTvuI8gbWludGxpZnk=",
  "type": "<string>",
  "scope": "restricted"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "type": "<string>",
  "scope": "<string>",
  "data": "<string>",
  "metadata": {
    "size": 123,
    "width": 123,
    "height": 123
  },
  "uri": "<string>"
}
Upload a single attachment to Penbox. Supports both JSON (base64) and multipart/form-data formats.
Size Limit: Maximum file size is 10GB per upload.

​
Query Parameters

​
company
string
Company UUID (optional if your token has company scope)

​
Request Body (JSON)

For JSON uploads, send base64-encoded file data:
​
name
string
required
File name
​
data
string
required
Base64-encoded file content
​
type
string
MIME type (e.g., “application/pdf”, “image/jpeg”). Optional - will be detected if not provided.
​
scope
string
default:"restricted"
Attachment visibility scope: public or restricted

​
Request Body (Multipart)

For multipart uploads, use multipart/form-data with a file field.

​
Response Structure

Returns a single attachment object: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "document.pdf",
  "type": "application/pdf",
  "uri": "https://connect.penbox.io/v1/attachments/550e8400-e29b-41d4-a716-446655440000",
  "metadata": {
    "size": 1024
  }
}

​
Response Codes

CodeDescription
201Created - File uploaded successfully
400Bad Request - Invalid file data
401Unauthorized - Invalid access token
403Forbidden - No company scope in token
413Payload Too Large - File exceeds 10GB limit
429Too Many Requests - Rate limit exceeded
500Server Error - Internal error
For large files, prefer multipart/form-data uploads as they’re more efficient. For small files or when embedding in JSON payloads, base64 encoding works well.

Authorizations

​
Authorization
string
header
required

API token (starts with pnbx_). Create at https://app.penbox.io/workspace/settings/api. Include as: Authorization: Bearer {token}

Query Parameters

​
workspace
string<uuid>

Workspace UUID (optional if token has workspace scope)

Body

​
name
string
required

File name

​
data
string<byte>
required

Base64-encoded file content

​
type
string

MIME type (optional, will be detected if not provided)

​
scope
enum<string>
default:restricted

Attachment visibility scope

Available options:
public,
restricted

Response

201 - application/json

File uploaded successfully

​
id
string<uuid>

Attachment UUID

​
name
string

Original filename

​
type
string

MIME type

​
scope
string | null

Attachment scope

​
data
string | null

Base64-encoded file content

​
metadata
object
​
uri
string<uri>

Direct download URL