Hostize API Docs

Programmatic access to Hostize services for Pro subscribers. Manage your files, generate download links, and automate your workflow.

Introduction

Hostize API allows you to programmatically manage your files. This API is available for Pro users only.

Welcome to the Hostize API documentation. Our API is organized around REST. Before we dive in to API, there are 2 entities we should know about Hostize: shares and materials.

A Share is a collection of files grouped together. When you upload files, they are organized into a share that can be accessed via a single link:https://www.hostize.com/s/{share_id}

Material

A Material is an individual file within a share. Each material has its own properties like name, size, and download count.

Note: The API is currently in beta. If you encounter any issues, please contact our support.

Authentication

How to authenticate your requests to the Hostize API.

All API requests must include an hostize-key header with your API key. You can manage your API keys in your profile settings.

curl -H "hostize-key: your_api_key_here" \
     https://www.hostize.com/api/v1/shares

List Shares

GET

/api/v1/shares

Retrieve a list of all your shares and their materials.

Example Request

curl -H "hostize-key: your_api_key" \
     https://www.hostize.com/api/v1/shares

Example Response

[
  {
    "id": "share_id",
    "userId": "user_id",
    "size": 2097152,
    "downloads": 5,
    "views": 10,
    "createdAt": "2024-01-20T20:25:00.000Z",
    "materials": [
      {
        "id": "material_1",
        "shareId": "share_id",
        "userId": "user_id",
        "name": "document.pdf",
        "size": 1048576,
        "format": "pdf",
        "mimeType": "application/pdf",
        "downloads": 2,
        "createdAt": "2024-01-20T20:25:00.000Z"
      },
      {
        "id": "material_2",
        "shareId": "share_id",
        "userId": "user_id",
        "name": "image.png",
        "size": 1048576,
        "format": "png",
        "mimeType": "image/png",
        "downloads": 3,
        "createdAt": "2024-01-20T20:25:00.000Z"
      }
    ]
  }
]

Get Share

GET

/api/v1/shares/{shareId}

Retrieve details of a specific share including its materials.

Parameters

Name	Description
shareId	The ID of the share

Example Request

curl -H "hostize-key: your_api_key" \
     https://www.hostize.com/api/v1/shares/share_id

Example Response

{
  "id": "share_id",
  "userId": "user_id",
  "size": 2097152,
  "downloads": 5,
  "views": 10,
  "createdAt": "2024-01-20T20:25:00.000Z",
  "materials": [
    {
      "id": "material_1",
      "shareId": "share_id",
      "userId": "user_id",
      "name": "document.pdf",
      "size": 1048576,
      "format": "pdf",
      "mimeType": "application/pdf",
      "downloads": 2,
      "createdAt": "2024-01-20T20:25:00.000Z"
    }
  ]
}

Delete Share

DELETE

/api/v1/shares/{shareId}

Delete a share and all its associated materials.

Parameters

Name	Description
shareId	The ID of the share to delete

Example Request

curl -X DELETE -H "hostize-key: your_api_key" \
     https://www.hostize.com/api/v1/shares/share_id

Example Response

HTTP/1.1 204 No Content

Request Upload

POST

/api/v1/upload/request

Start a new upload by requesting signed S3 URLs for your files.

Request Body

{
  "files": [
    {
      "name": "filename.ext",
      "size": 12345
    }
  ],
  "parts": 1 // optional
}

Small files (one part per file)

Example Request

curl -X POST -H "hostize-key: your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"files": [{"name": "file1.png", "size": 1024}, {"name": "file2.png", "size": 2048}]}' \
     https://www.hostize.com/api/v1/upload/request

Example Response

{
  "shareId": "new_share_id",
  "materials": [
    {
      "name": "file1.png",
      "partSize": 5242880,
      "partUrls": [{ "partNumber": 1, "url": "https://s3.signed.url/..." }]
    },
    {
      "name": "file2.png",
      "partSize": 5242880,
      "partUrls": [{ "partNumber": 1, "url": "https://s3.signed.url/..." }]
    }
  ]
}

Large files (multiple parts per file)

Example Request

curl -X POST -H "hostize-key: your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"files": [{"name": "large_video.mp4", "size": 104857600}, {"name": "archive.zip", "size": 31457280}], "parts": 5}' \
     https://www.hostize.com/api/v1/upload/request

Example Response

{
  "shareId": "new_share_id",
  "materials": [
    {
      "name": "large_video.mp4",
      "partSize": 20971520,
      "partUrls": [
        { "partNumber": 1, "url": "..." },
        { "partNumber": 2, "url": "..." },
        { "partNumber": 3, "url": "..." },
        { "partNumber": 4, "url": "..." },
        { "partNumber": 5, "url": "..." }
      ]
    },
    {
      "name": "archive.zip",
      "partSize": 10485760,
      "partUrls": [
        { "partNumber": 1, "url": "..." },
        { "partNumber": 2, "url": "..." },
        { "partNumber": 3, "url": "..." },
        { "partNumber": 4, "url": "..." },
        { "partNumber": 5, "url": "..." }
      ]
    }
  ]
}

Complete Upload

POST

/api/v1/upload/complete

After uploading all parts to S3, call this to finalize the upload.

Request Body

{
  "shareId": "share_id"
}

Example Request

curl -X POST -H "hostize-key: your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"shareId": "share_id"}' \
     https://www.hostize.com/api/v1/upload/complete

Example Response

{
  "id": "share_id",
  "userId": "user_id",
  "size": 1048576,
  "downloads": 0,
  "views": 0,
  "createdAt": "2024-01-20T20:25:00.000Z",
  "materials": [
    {
        "id": "material_1",
        "shareId": "share_id",
        "userId": "user_id",
        "name": "document.pdf",
        "size": 1048576,
        "format": "pdf",
        "mimeType": "application/pdf",
        "downloads": 2,
        "createdAt": "2024-01-20T20:25:00.000Z"
      },
      {
        "id": "material_2",
        "shareId": "share_id",
        "userId": "user_id",
        "name": "image.png",
        "size": 1048576,
        "format": "png",
        "mimeType": "image/png",
        "downloads": 3,
        "createdAt": "2024-01-20T20:25:00.000Z"
      }
  ]
}

Get Material

GET

/api/v1/materials/{materialId}

Retrieve details of a specific material.

Parameters

Name	Description
materialId	The ID of the material

Example Request

curl -H "hostize-key: your_api_key" \
     https://www.hostize.com/api/v1/materials/material_id

Example Response

{
  "id": "material_1",
  "shareId": "share_id",
  "userId": "user_id",
  "size": 1048576,
  "name": "document.pdf",
  "format": "pdf",
  "mimeType": "application/pdf",
  "downloads": 2,
  "createdAt": "2024-01-20T20:25:00.000Z"
}

Delete Material

DELETE

/api/v1/materials/{materialId}

Delete a specific material from its share.

Parameters

Name	Description
materialId	The ID of the material to delete

Example Request

curl -X DELETE -H "hostize-key: your_api_key" \
     https://www.hostize.com/api/v1/materials/material_id

Example Response

HTTP/1.1 204 No Content

Get Download URL

GET

/api/v1/materials/{materialId}/download-url

Get a temporary signed S3 download URL for a material.

Parameters

Name	Description
materialId	The ID of the material
expiresIn	Expiration time in seconds (default: 900)

Example Request

curl -H "hostize-key: your_api_key" \
     https://www.hostize.com/api/v1/materials/id/download-url

Example Response

{
  "url": "https://s3.signed.url/..."
}