> ## 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.

# Upload Attachment

> Upload one or more attachments. Supports both JSON (base64) and multipart/form-data formats.

Upload a single attachment to Penbox. Supports both JSON (base64) and multipart/form-data formats.

<Note>
  **Size Limit:** Maximum file size is 10GB per upload.
</Note>

## Query Parameters

<ParamField query="company" type="string">
  Company UUID (optional if your token has company scope)
</ParamField>

## Request Body (JSON)

For JSON uploads, send base64-encoded file data:

<ParamField body="name" type="string" required>
  File name
</ParamField>

<ParamField body="data" type="string" required>
  Base64-encoded file content
</ParamField>

<ParamField body="type" type="string">
  MIME type (e.g., "application/pdf", "image/jpeg"). Optional - will be detected if not provided.
</ParamField>

<ParamField body="scope" type="string" default="restricted">
  Attachment visibility scope: `public` or `restricted`
</ParamField>

## Request Body (Multipart)

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

## Response Structure

Returns a single attachment object:

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

| Code  | Description                                 |
| ----- | ------------------------------------------- |
| `201` | Created - File uploaded successfully        |
| `400` | Bad Request - Invalid file data             |
| `401` | Unauthorized - Invalid access token         |
| `403` | Forbidden - No company scope in token       |
| `413` | Payload Too Large - File exceeds 10GB limit |
| `429` | Too Many Requests - Rate limit exceeded     |
| `500` | Server Error - Internal error               |

<Tip>
  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.
</Tip>


## OpenAPI

````yaml POST /attachments
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:
    post:
      summary: Upload Attachments
      description: >-
        Upload one or more attachments. Supports both JSON (base64) and
        multipart/form-data formats.
      operationId: upload-attachments
      parameters:
        - name: workspace
          in: query
          description: Workspace UUID (optional if token has workspace scope)
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - data
              properties:
                name:
                  type: string
                  description: File name
                type:
                  type: string
                  description: MIME type (optional, will be detected if not provided)
                data:
                  type: string
                  format: byte
                  description: Base64-encoded file content
                scope:
                  type: string
                  enum:
                    - public
                    - restricted
                  default: restricted
                  description: Attachment visibility scope
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: File to upload
      responses:
        '201':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentFlat'
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}

````