REST API reference

Base URL: https://strovio.xyz/api/v1
Machine-readable: OpenAPI 3.1 document
Auth: Authorization: Bearer sk_live_..., or X-API-Key: sk_live_... if you cannot set an Authorization header. Create keys at strovio.xyz/developer.
Errors: JSON { "error": "...", "code": "...", "doc_url": "..." }. See Errors.
Keys: {path} is exactly the path you uploaded to, such as reports/q1.pdf, or the full key from a response, such as uploads/<account>/private/reports/q1.pdf. Encode each segment, for example a space as %20. If the path exists as both a public and a private file, the path alone returns 409 ambiguous_key.

File object

Field	Type	Notes
`key`	string	Full key: `uploads/<account>/<access>/<path>`
`name`	string	Your path on upload responses; the file name on list and get
`size`	integer	Bytes
`contentType`	string	Media type
`access`	`public` or `private`
`url`	string or null	Public URL, signed URL (get, private files) or null
`expiresIn`	integer or null	Get only: 3600 for private files, null for public
`createdAt`, `updatedAt`	string	ISO 8601

PUT /files/{path}

Upload or replace a file. Body: the raw bytes, up to 512 MB (536,870,912 bytes). Uploading to a path that exists with the same access replaces it; with the other access it creates a second file.

Headers: Content-Type (stored with the file), X-Access: public for a public file (default private).

201 returns the file object.

GET /files

List files, newest first. Query: prefix (key contains this text anywhere: reports/ also matches old/reports/x.pdf), limit (whole number from 1, default 1000, values above 1000 are treated as 1000).

200 returns { "objects": [file], "count": n }.

GET /files/{path}

Get a file's details and a download url. 200 returns the file object with expiresIn. 404 file_not_found if no file matches, 409 ambiguous_key if the path is both public and private.

HEAD /files/{path}

200 with Content-Length, Content-Type, X-Access and Last-Modified headers, 404 or 409. No body.

DELETE /files/{path}

Permanently delete a file and its share links. 200 returns { "ok": true, "key": "..." }.

POST /files/multipart/start

Body: { "key", "size", "contentType"?, "access"? }. 200 returns { "uploadId", "s3Key", "bucket", "parts": [{ "partNumber", "url", "contentLength" }] }. See Upload large files.

POST /files/multipart/complete

Body: { "s3Key", "uploadId", "key", "parts": [{ "PartNumber", "ETag" }], "contentType"?, "access"? }. 201 returns the file object.

POST /files/presign-put

Body: { "key", "size", "contentType"?, "access"? }. 200 returns { "putUrl", "s3Key", "bucket" }. PUT the bytes to putUrl within one hour with the same Content-Type.

POST /files/complete

Body: { "key", "contentType"?, "access"? }, after a successful PUT to a putUrl. 201 returns the file object.

GET /api/health

https://strovio.xyz/api/health needs no key and returns {"ok":true,...} when the service is up.

Idempotency and retries

Writes are keyed by path and access: retrying a PUT or a complete call with the same key and access replaces the same file and never creates a duplicate. The API does not store Idempotency-Key values. Retry 5xx errors with backoff; do not retry 4xx errors without changing the request. A retried DELETE whose first attempt succeeded returns 404 file_not_found.

Not available with an API key

Share links, folders, stars, trash, search and billing are dashboard features and need a signed-in browser session.