You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
correct FluxDrive API reference against the implementation
The cat/get/rm/thumb examples used ?arg=<HASH>, but all four read the hash
from the request body, so every documented command returned 400. Rewritten to
send the hash in the body.
Also corrected: /status and /ls response shapes (no status/result wrapper;
/ls returns files, files_per_page, total_files and takes four undocumented
pagination params), /put is single-file rather than multi, /putfolder returns
per-file outcomes inside a 200, the 401 error strings, the undocumented 403
IP allow-list, and HTTP 429 which is plain text rather than JSON.
Documents the self-service API key flow that now exists in the web UI.
@@ -33,8 +33,33 @@ Sign in at [cloud.runonflux.com/flux-drive](https://cloud.runonflux.com/flux-dri
33
33
34
34
#### 3. Generate an API Key
35
35
36
-
* In the FluxDrive web UI, generate an **API\_KEY\_SECRET** mapped to your FluxID
37
-
* Custom (PRO) plans can be arranged by contacting the Flux team — fill out the [PRO Plan Request Form](https://runonflux.bitrix24.com/pub/form/33_fluxdrive_pro_request_/2xp87g/?view=preview\&preview=inline) for a custom storage allocation
36
+
In the FluxDrive web UI, open the **API Keys** panel below your storage usage, then:
37
+
38
+
1. Click **Create key**
39
+
2. Give the key a name you'll recognise later (for example `production backup`)
40
+
3. Click **Generate**
41
+
4. Copy the key — or the ready-made `curl` command — from the dialog that appears
42
+
43
+
> ⚠️ **The key is shown only once.** FluxDrive stores only a hash of it, so it cannot be displayed or recovered again after you close that dialog. If you lose a key, revoke it and create a new one.
44
+
45
+
Custom (PRO) plans can be arranged by contacting the Flux team — fill out the [PRO Plan Request Form](https://runonflux.bitrix24.com/pub/form/33_fluxdrive_pro_request_/2xp87g/?view=preview\&preview=inline) for a custom storage allocation.
46
+
47
+
#### 4. Managing Your Keys
48
+
49
+
The same panel lists every key on your account, showing its name, first 8 characters, when it was created, and when it was last used — so you can tell which key an integration is actually using before you touch it.
50
+
51
+
| Action | How | Effect |
52
+
| ------ | --- | ------ |
53
+
|**Revoke a key**| Trash icon next to the key | Immediate. Any application using it starts receiving `401`. |
54
+
|**Create another**|**Create key**| Up to 10 keys per subscription. |
55
+
56
+
Some practical notes:
57
+
58
+
* Keys do not expire — they stay valid until you revoke them or the subscription lapses
59
+
* A key only works while the subscription is **active**; an unpaid or expired subscription returns `402` on every request
60
+
* Keys carry full access to your FluxDrive storage, so treat one like a password: keep it out of client-side code and out of version control
61
+
* Use a separate named key per application, so revoking one never takes down the others
62
+
* Keys cannot be used to create or revoke other keys — key management always requires a Zelcore signature from the web UI
38
63
39
64
***
40
65
@@ -57,45 +82,64 @@ All endpoints are accessed via **POST** requests with HTTP Basic authentication:
57
82
| Limit | Value | Notes |
58
83
| ----- | ----- | ----- |
59
84
| Maximum file size | 5 GB per file | Larger uploads return HTTP 413 |
60
-
| PUT rate limit | 150 requests / second | Per ZELID + IP |
61
-
| Read rate limit | 1500 requests / second | Per ZELID + IP, applies to `/cat`,`/get`, `/ls`, `/status`, `/thumb`|
85
+
| PUT rate limit | 150 requests / second | Per ZELID + IP, applies to `/put` and `/putfolder`|
86
+
| Read rate limit | 1500 requests / second | Per ZELID + IP, applies to every`/api/v0` endpoint|
62
87
| Storage capacity | Plan-dependent | See plans on the [overview page](README.md)|
88
+
| API keys | 10 per subscription | Revoke one to create another |
63
89
64
-
Exceeding a rate limit returns HTTP 429 with `Retry-After` headers.
90
+
Exceeding a rate limit returns HTTP 429. The rate-limit budget is keyed on your ZELID combined with your client IP, so separate machines using the same key each get their own allowance.
65
91
66
92
***
67
93
68
94
### Authentication & Errors
69
95
70
-
Every request must include valid Basic auth. Failed requests return JSON with an `error` field.
96
+
Every request must include valid Basic auth (`-u "<ZELID>:<API_KEY_SECRET>"`). Failed requests return JSON with an `error` field, except for rate limiting — see below.
71
97
72
-
**Common error responses:**
98
+
**Authentication failures**
99
+
100
+
| Status |`error`| Cause |
101
+
| ------ | ------- | ----- |
102
+
|`401`|`Missing or invalid Authorization header`| No `Authorization: Basic ...` header, or it could not be decoded |
103
+
|`401`|`Subscription not found`| No FluxDrive subscription exists for that ZELID |
104
+
|`401`|`Invalid API key`| The key is wrong, or it was revoked |
105
+
|`402`|`Subscription payment is not active`| Subscription is unpaid, expired, or cancelled |
106
+
|`403`|`IP address is not whitelisted`| Your account has an IP allow-list set and the request came from another address |
107
+
108
+
> ℹ️ **IP allow-listing is optional and off by default.** If you want your keys usable only from specific addresses, contact the Flux team to have an allow-list applied to your subscription.
109
+
110
+
**Request failures**
73
111
74
112
```json
75
-
// 401 — invalid or missing API key
76
-
{ "error": "Invalid credentials" }
113
+
// 400 — hash missing or malformed
114
+
{ "error": "Invalid or missing hash" }
115
+
116
+
// 400 — upload request carried no file
117
+
{ "error": "No file provided" }
77
118
78
-
// 402 — subscription not active (e.g., expired or unpaid)
119
+
// 402 — subscription lapsed between auth and upload
// 413 — upload would exceed your plan's storage capacity
83
126
{ "error": "Storage capacity exceeded" }
84
127
85
-
// 404 — hash not found in your account
128
+
// 404 — hash is not present in your account
86
129
{ "error": "File not found" }
87
-
88
-
// 429 — rate limited
89
-
{ "error": "Too many requests" }
90
130
```
91
131
132
+
> ⚠️ **HTTP 429 is not JSON.** Rate-limited requests return the plain-text body `Too many requests, please try again later.` — parse defensively rather than assuming an `error` field.
133
+
92
134
***
93
135
94
136
### Supported API Endpoints
95
137
138
+
All endpoints are **POST**. Parameters are sent in the **request body** (form-encoded or JSON), *not* as query-string arguments.
139
+
96
140
#### 1. `/api/v0/status`
97
141
98
-
**Description:** Get current storage usageand remaining capacity.
142
+
**Description:** Get current storage usage, capacity, and subscription state.
**Description:** Upload one or more files. Subject to the 5 GB per-file limit and your plan's storage capacity.
213
+
**Description:** Upload a **single file**. Subject to the 5 GB per-file limit and your plan's remaining capacity. To upload several files in one request, use `/putfolder`.
214
+
215
+
The form field name is not significant — the first uploaded file in the request is used.
> ℹ️ **`/putfolder` reports per-file outcomes.** The request can return `200` while individual entries carry an `error` field. Always inspect each entry rather than relying on the status code alone.
270
+
207
271
***
208
272
209
273
#### 5. `/api/v0/cat`
210
274
211
-
**Description:** Output the contents of a file from IPFS.
275
+
**Description:** Stream the contents of a file inline.
276
+
277
+
**Arguments:**
278
+
279
+
*`hash`_(string, required)_ — IPFS hash of a file in your account
Responses are served with `X-Content-Type-Options: nosniff`, and HTML/SVG/XML content types are downgraded to `application/octet-stream` so the API cannot be used to host executable web content.
222
289
223
290
***
224
291
225
292
#### 6. `/api/v0/get`
226
293
227
-
**Description:** Download a file from IPFS.
294
+
**Description:** Download a file as an attachment. Identical to `/cat` except that a `Content-Disposition: attachment` header is set.
**Description:** Remove a file from your FluxDrive account. The hash is unpinned from your subscription; if no other accounts pin it, the cluster will eventually garbage-collect the underlying blocks.
308
+
**Description:** Remove a file from your FluxDrive account. The hash is unpinned from your subscription; if no other account references it, the cluster will eventually garbage-collect the underlying blocks.
**Description:** Retrieve the generated thumbnail for a file, as `image/jpeg`. Returns `404` with `{ "error": "No thumbnail" }` when the file has none.
* All commands must be executed from a terminal (e.g., **VSCode integrated terminal**, **Ubuntu**, or similar).
264
-
* API access is protected via **ZELID** and **API\_KEY\_SECRET** — keep your key secret. If a key is leaked, rotate it immediately by generating a new one in the web UI.
342
+
* Parameters go in the request body — `/api/v0` does not read query-string arguments.
343
+
* API access is protected via **ZELID** and **API\_KEY\_SECRET** — keep your key secret. If a key is leaked, revoke it in the web UI and generate a replacement.
0 commit comments