> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get File

> Download or retrieve metadata for a specific attachment.

Download or retrieve metadata for a specific file (API: `attachment`).

<Note>
  In the API, uploaded files are referred to as **attachments**. This is the technical term used in all endpoints and parameters.
</Note>

<RequestExample>
  ```javascript Download File (JS) theme={null}
  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
  ```

  ```javascript Get Metadata (JS) theme={null}
  const fileId = '770e8400-e29b-41d4-a716-446655440000';

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

  const metadata = await response.json();
  console.log('Filename:', metadata.name);
  console.log('Size:', metadata.metadata.size);
  console.log('Type:', metadata.type);
  ```

  ```bash Download File (cURL) theme={null}
  curl -X GET 'https://connect.penbox.io/v1/attachments/670e8400-e29b-41d4-a716-446655440000' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Accept: application/octet-stream' \
    --output downloaded-file.pdf
  ```

  ```bash Get Metadata (cURL) theme={null}
  curl -X GET 'https://connect.penbox.io/v1/attachments/770e8400-e29b-41d4-a716-446655440000' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Accept: application/json'
  ```
</RequestExample>

## Response Formats

The endpoint supports two response formats controlled by the `Accept` header:

| Format     | Accept Header              | Use Case                                         |
| ---------- | -------------------------- | ------------------------------------------------ |
| **Binary** | `application/octet-stream` | Download the actual file                         |
| **JSON**   | `application/json`         | Get metadata and Base64 data (for files \< 50MB) |

### JSON Response

When using `Accept: application/json`, you'll receive:

```json theme={null}
{
  "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..."
}
```

| Field             | Type   | Description                                       |
| ----------------- | ------ | ------------------------------------------------- |
| `id`              | string | File UUID                                         |
| `name`            | string | Original filename                                 |
| `type`            | string | MIME type (e.g., `application/pdf`, `image/jpeg`) |
| `metadata.size`   | number | File size in bytes                                |
| `metadata.width`  | number | Image width in pixels (null for non-images)       |
| `metadata.height` | number | Image height in pixels (null for non-images)      |
| `uri`             | string | Direct download URL                               |
| `data`            | string | Base64-encoded file data (only for files \< 50MB) |

<Warning>
  Files larger than 50MB cannot be retrieved as JSON. Use `Accept: application/octet-stream` to download large files.
</Warning>

## Bulk Download

Download multiple files as a single ZIP archive:

```bash theme={null}
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

| Parameter  | Type   | Required | Description                                |
| ---------- | ------ | -------- | ------------------------------------------ |
| `ids`      | string | Yes      | Comma-separated list of file UUIDs         |
| `filename` | string | No       | Custom filename for the downloaded archive |

<Note>
  Multiple files are packaged as a ZIP archive for download.
</Note>

## Finding File IDs

File IDs are included when you retrieve a form response:

```javascript theme={null}
// 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:

| Category         | MIME Types                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Documents**    | `application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| **Images**       | `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/svg+xml`                                              |
| **Spreadsheets** | `application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `text/csv`        |
| **Archives**     | `application/zip`, `application/x-rar-compressed`, `application/x-7z-compressed`                                   |
| **Other**        | `text/plain`, `application/json`, `application/xml`                                                                |

## Response Codes

| Code  | Description                                                           |
| ----- | --------------------------------------------------------------------- |
| `200` | Success - File downloaded or metadata retrieved                       |
| `400` | Bad Request - Missing `ids` parameter (for bulk download)             |
| `401` | Unauthorized - Invalid access token                                   |
| `403` | Forbidden - No access to this file                                    |
| `404` | Not Found - File doesn't exist                                        |
| `413` | Payload Too Large - File too big for JSON response (use octet-stream) |
| `429` | Too Many Requests - Rate limit exceeded                               |
| `500` | Server Error - Internal error                                         |

<Note>
  Files are permanently stored and remain accessible even after the form is archived.
</Note>

<Tip>
  For large files (> 50MB), always use `Accept: application/octet-stream`. The JSON endpoint will return a 413 error for files exceeding this limit.
</Tip>

<Warning>
  Downloaded files should be scanned for viruses before processing, especially in production environments.
</Warning>


## OpenAPI

````yaml GET /attachments/{id}
openapi: 3.0.0
info:
  title: Penbox API
  version: '1.0'
  description: >-
    The Penbox API provides programmatic access to Penbox's form management,
    case management, and document processing capabilities. Authenticate using
    Bearer tokens created at https://app.penbox.io/workspace/settings/api
servers:
  - url: https://connect.penbox.io/v1
    description: Production
  - url: https://connect.aiboov.com/v1
    description: Staging
security:
  - BearerAuth: []
paths:
  /attachments/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: Attachment UUID
        schema:
          type: string
          format: uuid
    get:
      summary: Get Attachment
      description: Download or retrieve metadata for a specific attachment.
      operationId: get-attachment
      parameters:
        - name: Accept
          in: header
          description: >-
            Response format: application/json for metadata or
            application/octet-stream for file download
          schema:
            type: string
            enum:
              - application/json
              - application/octet-stream
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentFlat'
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: Binary file content
components:
  schemas:
    AttachmentFlat:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Attachment UUID
        name:
          type: string
          description: Original filename
        type:
          type: string
          description: MIME type
        scope:
          type: string
          nullable: true
          description: Attachment scope
        data:
          type: string
          nullable: true
          description: Base64-encoded file content
        metadata:
          type: object
          properties:
            size:
              type: integer
              description: File size in bytes
            width:
              type: integer
              nullable: true
            height:
              type: integer
              nullable: true
        uri:
          type: string
          format: uri
          description: Direct download URL
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: >-
        API token (starts with pnbx_). Create at
        https://app.penbox.io/workspace/settings/api. Include as: Authorization:
        Bearer {token}

````