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

# Create or Update One Folder Rule

> Creates or changes the rule of one folder prefix, leaving the other rules as they are.

Creates the rule for one folder prefix or changes it, and leaves the other rules alone. Put the prefix in the URL, URL-encoded (for example `tmp%2F`). The response is the whole list with its new `etag`.

**Scope:** `blob:write`.

<ParamField path="prefix" type="string" required>
  Folder prefix, URL-encoded. Stored with a trailing `/`.
</ParamField>

A rule needs at least one field besides the prefix; an empty rule returns `VALIDATION_ERROR`.

<ParamField body="visibility" type="string">
  Default visibility of new objects in the folder: `public` or `private`.
</ParamField>

<ParamField body="expire_seconds" type="number">
  Default expiration of each new object, in seconds. At least the plan's minimum expiration (7 days, or 1 hour on Enterprise-26 or higher).
</ParamField>

<ParamField body="max_size" type="number">
  Largest accepted file, 512 bytes to 10 GB.
</ParamField>

<ParamField body="extensions" type="string[]">
  Accepted extensions: 1–50 items, each 1–16 lowercase characters (letters and digits), without the dot.
</ParamField>

<ParamField body="cache_control" type="string">
  Default `cache_control` of new objects. `no-cache` needs Enterprise-26 or higher.
</ParamField>

<ParamField body="delete_after_days" type="number">
  Delete objects this many days after upload, 1–3650. Applies 24 hours after the rule is saved.
</ParamField>

<ParamField query="workspace_id" type="string">
  The workspace ID, when the blob belongs to a workspace. The call acts on the blob of the workspace owner and needs the `blob:read` workspace permission (`blob:manage` on routes that change data). Leave it out to act on your own blob.
</ParamField>

### Example request

```bash theme={null}
curl -X PUT "https://blob.vertracloud.app/v1/rules/tmp%2F" \
  -H "Authorization: Bearer $VERTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"delete_after_days":30}'
```

### Response

<ResponseField name="response" type="object">
  The whole rule list and its new etag.

  <Expandable title="properties">
    <ResponseField name="rules" type="object[]">Folder rules. The longest matching prefix applies.</ResponseField>
    <ResponseField name="rules[].prefix" type="string">Folder prefix, always stored with a trailing `/`.</ResponseField>
    <ResponseField name="rules[].visibility" type="string">Default visibility of new objects in the folder.</ResponseField>
    <ResponseField name="rules[].expire_seconds" type="number">Default expiration of each new object, in seconds.</ResponseField>
    <ResponseField name="rules[].max_size" type="number">Largest accepted file in bytes, 512 B to 10 GB.</ResponseField>
    <ResponseField name="rules[].extensions" type="string[]">Accepted extensions, 1–50, lowercase, without the dot.</ResponseField>
    <ResponseField name="rules[].cache_control" type="string">Default `cache_control` of new objects.</ResponseField>
    <ResponseField name="rules[].delete_after_days" type="number">Objects are deleted this many days after they're uploaded, 1–3650.</ResponseField>
    <ResponseField name="rules[].active_from" type="string">When `delete_after_days` starts to apply, set by the platform (24 hours after the rule is saved).</ResponseField>
    <ResponseField name="rules[].created_at" type="string">ISO 8601 time the rule was created.</ResponseField>
    <ResponseField name="etag" type="string">Version of the whole rule list. Send it back in `If-Match` when you replace the list.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "response": {
      "rules": [
        {
          "prefix": "tmp/",
          "delete_after_days": 30,
          "active_from": "2026-10-15T12:00:00.000Z",
          "created_at": "2026-10-14T12:00:00.000Z"
        }
      ],
      "etag": "v3"
    }
  }
  ```
</ResponseExample>

### Error Responses

<ResponseField name="code" type="string">
  The error code indicating the reason for failure. Possible values:

  * `AUTH_TOKEN_MISSING` (`401`): No `Authorization` header was sent.
  * `API_KEY_INVALID` (`401`): The API key doesn't exist, was revoked, or its secret doesn't match.
  * `API_KEY_SCOPE_DENIED` (`403`): The key lacks the scope this route needs (`blob:read` or `blob:write`); `details.required` names it.
  * `WORKSPACE_PERMISSION_DENIED` (`403`): Only with `workspace_id`: you're not a member, or your role lacks the blob permission.
  * `WORKSPACE_NOT_FOUND` (`404`): Only with `workspace_id`: no workspace with that ID, or you're not a member.
  * `BLOB_NAMESPACE_SUSPENDED` (`403`): The account's blob storage is suspended, or its plan expired. Uploads and other writes are refused from the start of the 72-hour grace period.
  * `VALIDATION_ERROR` (`400`): A parameter or body field failed validation. `details.path` names the field.
  * `BLOB_RULE_LIMIT` (`409`): Adding this rule would exceed the plan's rule limit: 5, 10 or 20.
  * `PLAN_RESTRICTED_FEATURE` (`403`): `cache_control` is `no-cache` on a plan below Enterprise-26.
</ResponseField>

<ResponseExample>
  ```json Error Response (401) theme={null}
  {
    "code": "AUTH_TOKEN_MISSING"
  }
  ```

  ```json Error Response (403) theme={null}
  {
    "code": "API_KEY_SCOPE_DENIED"
  }
  ```

  ```json Error Response (404) theme={null}
  {
    "code": "WORKSPACE_NOT_FOUND"
  }
  ```

  ```json Error Response (400) theme={null}
  {
    "code": "VALIDATION_ERROR"
  }
  ```

  ```json Error Response (409) theme={null}
  {
    "code": "BLOB_RULE_LIMIT"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.