---
title: "Create a CloudFS filesystem"
method: POST
path: "/storage/cloudfs"
tags: ["cloudfs filesystems"]
---

# Create a CloudFS filesystem

`POST /storage/cloudfs`

Creates a CloudFS filesystem. Provisioning is synchronous — typically a few seconds, up to a few minutes — and the filesystem is returned with status `ready`, together with its S3 bucket and metadata connection details. This response is the only time the filesystem's `meta_token` — and the credential-bearing `meta_url` — are returned; store them securely. If the token is lost, issue a new one with the rotate-meta-token action. Names are unique within your organization: creating with an existing name returns a `422`. Requests are idempotent: retrying with the same `Idempotency-Key` within 24 hours replays the original response instead of creating another filesystem.

## Headers

- `Idempotency-Key` string, required

## Request body

- CreateCloudfsFilesystemRequest
  - `name` string, required — Filesystem name, unique within your organization. Names are trimmed and lowercased; after normalization they may contain lowercase letters, numbers, `.`, `_`, and `-` only.
  - `region` 'us-central-1' | 'us-east-1' | 'us-west-1', required — Region where the filesystem's storage and metadata are provisioned.

## Response `201`

CloudFS filesystem created successfully. This is the only response (besides rotate-meta-token) that includes `meta_token`.

- CloudfsFilesystemResponseWrapper
  - `data` CloudfsFilesystem — A CloudFS filesystem, including its metadata credential. This shape is returned only by create and rotate-meta-token.
    - `record_type` string
    - `id` string, uuid
    - `name` string
    - `status` 'provisioning' | 'ready' | 'needs_format' | 'deleting' | 'failed' | 'deleted' — Lifecycle status of the filesystem. `ready` means it is fully provisioned and usable. `needs_format` means the storage bucket and metadata database were provisioned but the filesystem has not yet been formatted — run `juicefs format` with the filesystem's `meta_url` before mounting. `failed` means the last lifecycle action failed — see the filesystem's `error` message. `deleted` appears only in the delete response: deleted filesystems are excluded from list results and return a `404` on retrieval.
    - `meta_url` string — PostgreSQL connection URL for the filesystem's metadata database. In create and rotate-meta-token responses it embeds the metadata token as the password: `postgres://<database>:<meta_token>@us-east-1.telnyxcloudfs.com:5432/<database>?sslmode=require` (the example below is shown without the credential; the actual response includes it). Pass it to `juicefs mount`: the storage configuration is baked in at provisioning, so the metadata URL is all a client needs to mount the filesystem.
    - `meta_token` string — Metadata access token, in cleartext. Returned only by create and rotate-meta-token and not retrievable afterwards — store it securely.
    - `s3_endpoint` string — URL of the Telnyx Cloud Storage endpoint backing this filesystem.
    - `s3_bucket` string — Name of the bucket that stores this filesystem's data. Created during provisioning.
    - `region` string
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `400` — Bad request — malformed JSON, unknown field, or a missing or invalid `Idempotency-Key` header
- `401` — Unauthorized
- `409` — Conflict — a request with this `Idempotency-Key` is still being processed
- `422` — Unprocessable entity — missing or invalid `name` or `region`, a filesystem with this name already exists for your organization, or the `Idempotency-Key` was already used for a different request
- `500` — Internal server error

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/revisions/8f5f4e537994/schema)