**גרסאות API** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=he)

# Uploads

OpenAPI 3.0.3 · API 2.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v2",
    "description": "API"
  }
]
```

Public organisation file hosting shared by email, website and document workflows. JSON bytes or public URL imports are callable through MCP; REST also accepts multipart uploads.

## פעולות

## POST /uploads

Upload a media file from bytes or a public URL

`create_upload`

Required scope: `uploads:write`. The generic REST endpoint also accepts `messages:write` for compatibility.

Accepts supported raster images up to 5 MiB, PDFs up to 15 MiB and videos up to 20 MiB.

Stores one file in this organisation and returns its public hosted URL and filename. Choose exactly one source: contentBase64 with mimeType for actual file bytes, or url for an existing publicly reachable HTTP(S) file. filename is optional display metadata. Raw standard padded base64 only, without a data URL prefix; never invent bytes or send a local path, attachment ID or private sandbox URL. The AI host must provide access to the actual attachment bytes or a public URL. Maximum decoded sizes are image 5 MiB, PDF 15 MiB and video 20 MiB. Actual bytes, MIME type, size and ownership are checked before publication; SVG, HTML, scripts, archives and other file types are refused. Uploading publishes the file to anyone holding its URL, so use only material authorised for public hosting. It does not attach the file to a page, send an email or change the organisation logo. Use the returned url in email/page HTML, or filename where a destination expects an owned asset. For an email logo, upload the image, save the template HTML with its returned url, then give the user the template previewUrl. REST also retains its existing multipart transport. Identical bytes reuse the organisation asset; after an uncertain result, retry the same bytes rather than change the file.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "uploads:write",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "multipart/form-data": {
      "schema": {
        "type": "object",
        "minProperties": 1,
        "maxProperties": 1,
        "additionalProperties": {
          "type": "string",
          "format": "binary"
        }
      },
      "x-unisoft-file-policy": [
        {
          "contentType": "image/*",
          "maxBytes": 5242880
        },
        {
          "contentType": "application/pdf",
          "maxBytes": 15728640
        },
        {
          "contentType": "video/*",
          "maxBytes": 20971520
        }
      ]
    },
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_695f3576db52b08c3bf5"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UploadResult"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UNSUPPORTED_MEDIA_TYPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "UNSUPPORTED_MEDIA_TYPE"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "uploads:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /uploads/image

Upload an image from bytes or a public URL

`create_upload_image`

Required scope: `uploads:write`.

Accepts supported raster images only, up to 5 MiB.

Stores one file in this organisation and returns its public hosted URL and filename. Choose exactly one source: contentBase64 with mimeType for actual file bytes, or url for an existing publicly reachable HTTP(S) file. filename is optional display metadata. Raw standard padded base64 only, without a data URL prefix; never invent bytes or send a local path, attachment ID or private sandbox URL. The AI host must provide access to the actual attachment bytes or a public URL. Maximum decoded sizes are image 5 MiB, PDF 15 MiB and video 20 MiB. Actual bytes, MIME type, size and ownership are checked before publication; SVG, HTML, scripts, archives and other file types are refused. Uploading publishes the file to anyone holding its URL, so use only material authorised for public hosting. It does not attach the file to a page, send an email or change the organisation logo. Use the returned url in email/page HTML, or filename where a destination expects an owned asset. For an email logo, upload the image, save the template HTML with its returned url, then give the user the template previewUrl. REST also retains its existing multipart transport. Identical bytes reuse the organisation asset; after an uncertain result, retry the same bytes rather than change the file.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "uploads:write",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "multipart/form-data": {
      "schema": {
        "type": "object",
        "minProperties": 1,
        "maxProperties": 1,
        "additionalProperties": {
          "type": "string",
          "format": "binary"
        }
      },
      "x-unisoft-file-policy": [
        {
          "contentType": "image/*",
          "maxBytes": 5242880
        }
      ]
    },
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_3f4d6f556799cc1fe37a"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UploadResult"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "WRONG_MEDIA_FAMILY",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "WRONG_MEDIA_FAMILY"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "uploads:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /uploads/pdf

Upload a PDF from bytes or a public URL

`create_upload_pdf`

Required scope: `uploads:write`.

Accepts PDF files only, up to 15 MiB.

Stores one file in this organisation and returns its public hosted URL and filename. Choose exactly one source: contentBase64 with mimeType for actual file bytes, or url for an existing publicly reachable HTTP(S) file. filename is optional display metadata. Raw standard padded base64 only, without a data URL prefix; never invent bytes or send a local path, attachment ID or private sandbox URL. The AI host must provide access to the actual attachment bytes or a public URL. Maximum decoded sizes are image 5 MiB, PDF 15 MiB and video 20 MiB. Actual bytes, MIME type, size and ownership are checked before publication; SVG, HTML, scripts, archives and other file types are refused. Uploading publishes the file to anyone holding its URL, so use only material authorised for public hosting. It does not attach the file to a page, send an email or change the organisation logo. Use the returned url in email/page HTML, or filename where a destination expects an owned asset. For an email logo, upload the image, save the template HTML with its returned url, then give the user the template previewUrl. REST also retains its existing multipart transport. Identical bytes reuse the organisation asset; after an uncertain result, retry the same bytes rather than change the file.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "uploads:write",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "multipart/form-data": {
      "schema": {
        "type": "object",
        "minProperties": 1,
        "maxProperties": 1,
        "additionalProperties": {
          "type": "string",
          "format": "binary"
        }
      },
      "x-unisoft-file-policy": [
        {
          "contentType": "application/pdf",
          "maxBytes": 15728640
        }
      ]
    },
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_2e8d05753d86e4582298"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UploadResult"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "WRONG_MEDIA_FAMILY",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "WRONG_MEDIA_FAMILY"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "uploads:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## סכמות

```json
{
  "components": {
    "schemas": {
      "UnisoftRequest_695f3576db52b08c3bf5": {
        "type": "object",
        "properties": {
          "contentBase64": {
            "type": "string",
            "minLength": 4,
            "maxLength": 27962028,
            "format": "byte",
            "description": "Actual file bytes encoded as raw standard padded base64, without a data URL prefix. Required with mimeType when url is absent."
          },
          "mimeType": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Actual media MIME type, such as image/png, image/jpeg or application/pdf. Required with contentBase64; omitted for url imports."
          },
          "filename": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Optional original display filename. It never selects a server path, stored name or file type."
          },
          "url": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096,
            "format": "uri",
            "description": "Public HTTP(S) source URL to import. Private destinations, credentials and unsafe redirects are refused. Omit contentBase64 and mimeType."
          }
        },
        "additionalProperties": false,
        "oneOf": [
          {
            "required": [
              "contentBase64",
              "mimeType"
            ],
            "not": {
              "required": [
                "url"
              ]
            }
          },
          {
            "required": [
              "url"
            ],
            "not": {
              "anyOf": [
                {
                  "required": [
                    "contentBase64"
                  ]
                },
                {
                  "required": [
                    "mimeType"
                  ]
                }
              ]
            }
          }
        ]
      },
      "UploadResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "filename",
              "url",
              "mimetype",
              "size"
            ],
            "properties": {
              "filename": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "mimetype": {
                "type": "string"
              },
              "size": {
                "type": "integer",
                "minimum": 1,
                "maximum": 20971520
              }
            }
          }
        }
      },
      "UnisoftRequest_3f4d6f556799cc1fe37a": {
        "type": "object",
        "properties": {
          "contentBase64": {
            "type": "string",
            "minLength": 4,
            "maxLength": 6990508,
            "format": "byte",
            "description": "Actual file bytes encoded as raw standard padded base64, without a data URL prefix. Required with mimeType when url is absent."
          },
          "mimeType": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Actual media MIME type, such as image/png, image/jpeg or application/pdf. Required with contentBase64; omitted for url imports."
          },
          "filename": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Optional original display filename. It never selects a server path, stored name or file type."
          },
          "url": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096,
            "format": "uri",
            "description": "Public HTTP(S) source URL to import. Private destinations, credentials and unsafe redirects are refused. Omit contentBase64 and mimeType."
          }
        },
        "additionalProperties": false,
        "oneOf": [
          {
            "required": [
              "contentBase64",
              "mimeType"
            ],
            "not": {
              "required": [
                "url"
              ]
            }
          },
          {
            "required": [
              "url"
            ],
            "not": {
              "anyOf": [
                {
                  "required": [
                    "contentBase64"
                  ]
                },
                {
                  "required": [
                    "mimeType"
                  ]
                }
              ]
            }
          }
        ]
      },
      "UnisoftRequest_2e8d05753d86e4582298": {
        "type": "object",
        "properties": {
          "contentBase64": {
            "type": "string",
            "minLength": 4,
            "maxLength": 20971520,
            "format": "byte",
            "description": "Actual file bytes encoded as raw standard padded base64, without a data URL prefix. Required with mimeType when url is absent."
          },
          "mimeType": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Actual media MIME type, such as image/png, image/jpeg or application/pdf. Required with contentBase64; omitted for url imports."
          },
          "filename": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Optional original display filename. It never selects a server path, stored name or file type."
          },
          "url": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096,
            "format": "uri",
            "description": "Public HTTP(S) source URL to import. Private destinations, credentials and unsafe redirects are refused. Omit contentBase64 and mimeType."
          }
        },
        "additionalProperties": false,
        "oneOf": [
          {
            "required": [
              "contentBase64",
              "mimeType"
            ],
            "not": {
              "required": [
                "url"
              ]
            }
          },
          {
            "required": [
              "url"
            ],
            "not": {
              "anyOf": [
                {
                  "required": [
                    "contentBase64"
                  ]
                },
                {
                  "required": [
                    "mimeType"
                  ]
                }
              ]
            }
          }
        ]
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
