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

# Blob Create Share

> Create a share link with POST /v1/shares: valid up to 30 days, revocable, with an optional download cap and, on Pro and Enterprise, a password.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security).
</ParamField>

Create Share makes a link (`https://files.squarecloud.dev/s/...`) to hand one file to people: a client, a team, a tester. It works for public and private files, lasts up to 30 days, can be revoked at any time and can limit how many times the file is downloaded. On **Pro and Enterprise** it can also ask for a password. Requires the `blob:write` scope.

Opening the link downloads the file. A password-protected link first shows a page asking for the password, in the visitor's language. The link is tied to the file's current id: deleting, moving or changing the visibility of the file makes it answer `404` right away, without spending a download. See [Links and sharing](/en/blob-reference/links-and-sharing) for how it compares to temporary links.

<ParamField body="object" type="string" required>
  The id of the file to share.
</ParamField>

<ParamField body="expires_in" type="number" default="86400">
  How long the link lasts, from 60 to 2592000 seconds (30 days).
</ParamField>

<ParamField body="max_downloads" type="number">
  How many downloads the link allows, from 1 to 10000. Once spent, it answers `410`. Without it, there is no cap.
</ParamField>

<ParamField body="password" type="string">
  A password of 8 to 128 characters the visitor must type before downloading. Pro and Enterprise only.
</ParamField>

<Warning>For a **public** file the link redirects to its permanent public URL, which anyone who opens it can keep using. The password, the download cap and the expiry only truly protect **private** files.</Warning>

### Limits

<Note>
  * 30 links per minute (`RATE_LIMITED`, 429), and up to 1000 active links per account (`TOO_MANY_SHARES`, 409).
  * Each link accepts 120 visits per minute per IP. Wrong passwords are limited per IP and per link.
  * Downloading a private file goes through a temporary link: 60 requests per minute per IP, plus the overall limit of your account. To hand a file to many people, make it public.
</Note>

### Response

Answers `201 Created`.

<ResponseField name="status" type="string">
  "success" if successful, "error" if not.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Toggle object">
    <ResponseField name="id" type="string">
      The share id. Use it with [Delete Share](/en/blob-reference/endpoint/shares-delete).
    </ResponseField>

    <ResponseField name="url" type="string">
      The link to hand out.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601">
      When the link expires.
    </ResponseField>

    <ResponseField name="max_downloads" type="number | null">
      The download cap, or `null`.
    </ResponseField>

    <ResponseField name="password" type="boolean">
      Whether the link asks for a password.
    </ResponseField>

    <ResponseField name="object" type="string">
      The id of the shared file.
    </ResponseField>

    <ResponseField name="object_is_public" type="boolean">
      `true` when the file is public: anyone with its public URL can still download it, so revoking, capping or protecting the share doesn't restrict access to the file itself.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://blob.squarecloud.app/v1/shares' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
      "expires_in": 604800,
      "max_downloads": 5
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://blob.squarecloud.app/v1/shares', {
    method: 'POST',
    headers: {
      Authorization: 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      object: 'prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf',
      expires_in: 7 * 24 * 60 * 60,
      max_downloads: 5,
    }),
  });
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "id": "q8Zr2LwX7nT0vKc4Hs1YbA",
      "url": "https://files.squarecloud.dev/s/q8Zr2LwX7nT0vKc4Hs1YbA",
      "expires_at": "2026-10-02T12:00:00.000Z",
      "max_downloads": 5,
      "password": false,
      "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
      "object_is_public": false
    }
  }
  ```
</ResponseExample>

### Errors

| Code                    | HTTP | When                                                  |
| ----------------------- | ---- | ----------------------------------------------------- |
| `INVALID_OBJECT`        | 400  | `object` is missing, malformed or not yours.          |
| `INVALID_EXPIRES_IN`    | 400  | `expires_in` is not an integer from 60 to 2592000.    |
| `INVALID_MAX_DOWNLOADS` | 400  | `max_downloads` is not an integer from 1 to 10000.    |
| `INVALID_PASSWORD`      | 400  | The password doesn't have 8 to 128 characters.        |
| `UPGRADE_REQUIRED`      | 403  | Passwords need Pro or Enterprise.                     |
| `OBJECT_NOT_FOUND`      | 404  | The file doesn't exist.                               |
| `TOO_MANY_SHARES`       | 409  | The account has 1000 active links. Revoke some first. |
| `RATE_LIMITED`          | 429  | More than 30 links in a minute.                       |