Skip to main content
GET
/
attachments
/
{id}
const fileId = '670e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://connect.penbox.io/v1/attachments/${fileId}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/octet-stream'
    }
  }
);

const blob = await response.blob();
// Save or process the file

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "type": "<string>",
  "scope": "<string>",
  "data": "<string>",
  "metadata": {
    "size": 123,
    "width": 123,
    "height": 123
  },
  "uri": "<string>"
}
Download or retrieve metadata for a specific file (API: attachment).
In the API, uploaded files are referred to as attachments. This is the technical term used in all endpoints and parameters.
const fileId = '670e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://connect.penbox.io/v1/attachments/${fileId}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/octet-stream'
    }
  }
);

const blob = await response.blob();
// Save or process the file

​
Response Formats

The endpoint supports two response formats controlled by the Accept header:
FormatAccept HeaderUse Case
Binaryapplication/octet-streamDownload the actual file
JSONapplication/jsonGet metadata and Base64 data (for files < 50MB)

​
JSON Response

When using Accept: application/json, you’ll receive: 
{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "name": "passport.pdf",
  "type": "application/pdf",
  "metadata": {
    "size": 245678,
    "width": null,
    "height": null
  },
  "uri": "https://connect.penbox.io/v1/attachments/770e8400-e29b-41d4-a716-446655440000",
  "data": "JVBERi0xLjQKJeLjz9MKJSVJU0lTIEREREVfUGRmLVY3LjEg..."
}
FieldTypeDescription
idstringFile UUID
namestringOriginal filename
typestringMIME type (e.g., application/pdf, image/jpeg)
metadata.sizenumberFile size in bytes
metadata.widthnumberImage width in pixels (null for non-images)
metadata.heightnumberImage height in pixels (null for non-images)
uristringDirect download URL
datastringBase64-encoded file data (only for files < 50MB)
Files larger than 50MB cannot be retrieved as JSON. Use Accept: application/octet-stream to download large files.

​
Bulk Download

Download multiple files as a single ZIP archive: 
curl -X GET 'https://connect.penbox.io/v1/attachments?ids=id1,id2,id3&filename=documents' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/octet-stream' \
  --output documents.zip

​
Query Parameters

ParameterTypeRequiredDescription
idsstringYesComma-separated list of file UUIDs
filenamestringNoCustom filename for the downloaded archive
Multiple files are packaged as a ZIP archive for download.

​
Finding File IDs

File IDs are included when you retrieve a form response: 
// Get response with files
const { data, included } = await fetch(
  `https://connect.penbox.io/v1/responses/${responseId}`,
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
).then(r => r.json());

// Extract file IDs from included resources
const files = included.filter(item => item.type === 'attachments');

for (const file of files) {
  console.log('File ID:', file.id);
  console.log('Filename:', file.attributes.name);
  console.log('Size:', file.attributes.metadata.size);

  // Download the file
  await downloadFile(file.id, accessToken);
}

​
Supported File Types

Penbox supports various file types:
CategoryMIME Types
Documentsapplication/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document
Imagesimage/jpeg, image/png, image/gif, image/webp, image/svg+xml
Spreadsheetsapplication/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, text/csv
Archivesapplication/zip, application/x-rar-compressed, application/x-7z-compressed
Othertext/plain, application/json, application/xml

​
Response Codes

CodeDescription
200Success - File downloaded or metadata retrieved
400Bad Request - Missing ids parameter (for bulk download)
401Unauthorized - Invalid access token
403Forbidden - No access to this file
404Not Found - File doesn’t exist
413Payload Too Large - File too big for JSON response (use octet-stream)
429Too Many Requests - Rate limit exceeded
500Server Error - Internal error
Files are permanently stored and remain accessible even after the form is archived.
For large files (> 50MB), always use Accept: application/octet-stream. The JSON endpoint will return a 413 error for files exceeding this limit.
Downloaded files should be scanned for viruses before processing, especially in production environments.

Authorizations

​
Authorization
string
header
required

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

Headers

​
Accept
enum<string>

Response format: application/json for metadata or application/octet-stream for file download

Available options:
application/json,
application/octet-stream

Path Parameters

​
id
string<uuid>
required

Attachment UUID

Response

Successful response

​
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