Developers

Sharable File API

1.0.0OAS3

Upload, list, download, replace, patch, and delete files in your API Upload library. Authenticate with x-api-key. Pro plan only. Uploads are public so the share link works.

https://sharable.ryples.com

Get an API key openapi.json

Files

POST

/api/v1/files

Upload a file

Multipart upload into your API Upload inbox. New files are public so the returned link works. Size and storage quotas still apply. POST /api/files/upload remains a thin alias.

Auth: x-api-key · Pro only

Request body

multipart/form-data

Field	Type	Description
file*	binary	The file to store in your API Upload library.
expires	string	never, a preset (30m, 1h, 1d, 7d, 1w, 30d), or a file.io-style duration such as 2h or 7d.
maxDownloads	integer	Download cap. 0 means unlimited. 1 also enables burn-after-download.
autoDelete	boolean	Accepted for compatibility; responses always report true. Expired files are removed by cleanup.
password	string	Optional password on the public share link.

Examples

curl -X POST "https://sharable.ryples.com/api/v1/files" \
  -H "x-api-key: sh-YOUR_API_KEY" \
  -F "file=@/path/to/report.pdf" \
  -F "expires=7d" \
  -F "maxDownloads=0" \
  -F "autoDelete=true"

Responses

200File stored.FileDetails

{
  "success": true,
  "id": "64f0c2a91b3e4a0012ab34cd",
  "key": "64f0c2a91b3e4a0012ab34cd",
  "name": "report.pdf",
  "link": "https://example.com/files/p/64f0c2a91b3e4a0012ab34cd",
  "download": "https://example.com/api/v1/files/64f0c2a91b3e4a0012ab34cd/download",
  "expires": "2026-08-21T00:00:00.000Z",
  "expiry": "7d",
  "downloads": 0,
  "maxDownloads": 0,
  "autoDelete": true,
  "size": 1234,
  "mimeType": "application/pdf",
  "created": "2026-08-14T00:00:00.000Z",
  "modified": "2026-08-14T00:00:00.000Z"
}

400Missing file field or invalid multipart values.Error

{
  "success": false,
  "error": "No file provided. Use form field \"file\"."
}

401Missing or invalid API key.Error

{
  "success": false,
  "error": "Invalid API key"
}

403Caller is not on Pro.Error

{
  "success": false,
  "error": "API upload is available on Pro. Redeem a code on the pricing page."
}

GET

/api/v1/files

List files

Page through files in the API Upload inbox only — not personal Files, notes, or vault.

Auth: x-api-key · Pro only

Parameters

Name	In	Type	Description
search	query	string	Case-insensitive name match.
sort	query	string	created, modified, name, or size. Prefix - for descending (default -created).
offset	query	integer	Number of items to skip. Default 0.
limit	query	integer	Page size, 1–100. Default 20.

Examples

curl -X GET "https://sharable.ryples.com/api/v1/files?search=report&sort=-created&offset=0&limit=20" \
  -H "x-api-key: sh-YOUR_API_KEY"

Responses

200A page of files.FileList

{
  "success": true,
  "items": [
    {
      "success": true,
      "id": "64f0c2a91b3e4a0012ab34cd",
      "key": "64f0c2a91b3e4a0012ab34cd",
      "name": "report.pdf",
      "link": "https://example.com/files/p/64f0c2a91b3e4a0012ab34cd",
      "download": "https://example.com/api/v1/files/64f0c2a91b3e4a0012ab34cd/download",
      "expires": "2026-08-21T00:00:00.000Z",
      "expiry": "7d",
      "downloads": 0,
      "maxDownloads": 0,
      "autoDelete": true,
      "size": 1234,
      "mimeType": "application/pdf",
      "created": "2026-08-14T00:00:00.000Z",
      "modified": "2026-08-14T00:00:00.000Z"
    }
  ],
  "offset": 0,
  "limit": 20,
  "count": 1
}

401Missing or invalid API key.Error

{
  "success": false,
  "error": "Invalid API key"
}

403Caller is not on Pro.Error

{
  "success": false,
  "error": "API upload is available on Pro. Redeem a code on the pricing page."
}

GET

/api/v1/files/{id}

Get file metadata

Return FileDetails for one API Upload file.

Auth: x-api-key · Pro only

Parameters

Name	In	Type	Description
id*	path	string	File id returned on upload (same as key).

Examples

curl -X GET "https://sharable.ryples.com/api/v1/files/64f0c2a91b3e4a0012ab34cd" \
  -H "x-api-key: sh-YOUR_API_KEY"

Responses

200File metadata.FileDetails

{
  "success": true,
  "id": "64f0c2a91b3e4a0012ab34cd",
  "key": "64f0c2a91b3e4a0012ab34cd",
  "name": "report.pdf",
  "link": "https://example.com/files/p/64f0c2a91b3e4a0012ab34cd",
  "download": "https://example.com/api/v1/files/64f0c2a91b3e4a0012ab34cd/download",
  "expires": "2026-08-21T00:00:00.000Z",
  "expiry": "7d",
  "downloads": 0,
  "maxDownloads": 0,
  "autoDelete": true,
  "size": 1234,
  "mimeType": "application/pdf",
  "created": "2026-08-14T00:00:00.000Z",
  "modified": "2026-08-14T00:00:00.000Z"
}

401Missing or invalid API key.Error

{
  "success": false,
  "error": "Invalid API key"
}

404Unknown id, or the file is not in the API inbox.Error

{
  "success": false,
  "error": "File not found"
}

GET

/api/v1/files/{id}/download

Download file bytes

Stream the stored blob. Counts toward downloads and may purge the file when maxDownloads or burn-after-download is reached.

Auth: x-api-key · Pro only

Parameters

Name	In	Type	Description
id*	path	string	File id returned on upload (same as key).

Examples

curl -X GET "https://sharable.ryples.com/api/v1/files/64f0c2a91b3e4a0012ab34cd/download" \
  -H "x-api-key: sh-YOUR_API_KEY" \
  -o report.pdf

Responses

200File bytes.

application/octet-stream

401Missing or invalid API key.Error

{
  "success": false,
  "error": "Invalid API key"
}

404Unknown id.Error

{
  "success": false,
  "error": "File not found"
}

410Blob is gone.Error

{
  "success": false,
  "error": "File is no longer available"
}

PUT

/api/v1/files/{id}

Replace a file

Replace the blob. Multipart fields you omit reset to defaults (unlike PATCH).

Auth: x-api-key · Pro only

Parameters

Name	In	Type	Description
id*	path	string	File id returned on upload (same as key).

Request body

multipart/form-data

Field	Type	Description
file*	binary	Replacement blob. Unspecified metadata fields reset to defaults.
expires	string	never, a preset (30m, 1h, 1d, 7d, 1w, 30d), or a file.io-style duration such as 2h or 7d.
maxDownloads	integer	Download cap. 0 means unlimited. 1 also enables burn-after-download.
autoDelete	boolean	Accepted for compatibility; responses always report true. Expired files are removed by cleanup.
password	string	Optional password on the public share link.

Examples

curl -X PUT "https://sharable.ryples.com/api/v1/files/64f0c2a91b3e4a0012ab34cd" \
  -H "x-api-key: sh-YOUR_API_KEY" \
  -F "file=@/path/to/report.pdf" \
  -F "expires=7d" \
  -F "maxDownloads=0" \
  -F "autoDelete=true"

Responses

200Updated file.FileDetails

{
  "success": true,
  "id": "64f0c2a91b3e4a0012ab34cd",
  "key": "64f0c2a91b3e4a0012ab34cd",
  "name": "report.pdf",
  "link": "https://example.com/files/p/64f0c2a91b3e4a0012ab34cd",
  "download": "https://example.com/api/v1/files/64f0c2a91b3e4a0012ab34cd/download",
  "expires": "2026-08-21T00:00:00.000Z",
  "expiry": "7d",
  "downloads": 0,
  "maxDownloads": 0,
  "autoDelete": true,
  "size": 1234,
  "mimeType": "application/pdf",
  "created": "2026-08-14T00:00:00.000Z",
  "modified": "2026-08-14T00:00:00.000Z"
}

400Missing file field or invalid multipart values.Error

{
  "success": false,
  "error": "No file provided. Use form field \"file\"."
}

401Missing or invalid API key.Error

{
  "success": false,
  "error": "Invalid API key"
}

404Unknown id.Error

{
  "success": false,
  "error": "File not found"
}

PATCH

/api/v1/files/{id}

Update file metadata

Partial update. Unspecified fields are kept. File is optional.

Auth: x-api-key · Pro only

Parameters

Name	In	Type	Description
id*	path	string	File id returned on upload (same as key).

Request body

multipart/form-data

Field	Type	Description
file	binary	Optional new blob. Omitted fields are kept as-is.
expires	string	never, a preset (30m, 1h, 1d, 7d, 1w, 30d), or a file.io-style duration such as 2h or 7d. Omitted values are kept.
maxDownloads	integer	Download cap. 0 means unlimited. 1 also enables burn-after-download. Omitted values are kept.
autoDelete	boolean	Accepted for compatibility; responses always report true. Expired files are removed by cleanup. Omitted values are kept.
password	string	Optional password on the public share link. Omitted values are kept.

Examples

curl -X PATCH "https://sharable.ryples.com/api/v1/files/64f0c2a91b3e4a0012ab34cd" \
  -H "x-api-key: sh-YOUR_API_KEY" \
  -F "file=@/path/to/report.pdf" \
  -F "expires=7d" \
  -F "maxDownloads=0" \
  -F "autoDelete=true"

Responses

200Updated file.FileDetails

{
  "success": true,
  "id": "64f0c2a91b3e4a0012ab34cd",
  "key": "64f0c2a91b3e4a0012ab34cd",
  "name": "report.pdf",
  "link": "https://example.com/files/p/64f0c2a91b3e4a0012ab34cd",
  "download": "https://example.com/api/v1/files/64f0c2a91b3e4a0012ab34cd/download",
  "expires": "2026-08-21T00:00:00.000Z",
  "expiry": "7d",
  "downloads": 0,
  "maxDownloads": 0,
  "autoDelete": true,
  "size": 1234,
  "mimeType": "application/pdf",
  "created": "2026-08-14T00:00:00.000Z",
  "modified": "2026-08-14T00:00:00.000Z"
}

400Invalid multipart values.Error

{
  "success": false,
  "error": "Invalid maxDownloads value"
}

401Missing or invalid API key.Error

{
  "success": false,
  "error": "Invalid API key"
}

404Unknown id.Error

{
  "success": false,
  "error": "File not found"
}

DELETE

/api/v1/files/{id}

Delete a file

Permanently remove an API Upload file and its blob.

Auth: x-api-key · Pro only

Parameters

Name	In	Type	Description
id*	path	string	File id returned on upload (same as key).

Examples

curl -X DELETE "https://sharable.ryples.com/api/v1/files/64f0c2a91b3e4a0012ab34cd" \
  -H "x-api-key: sh-YOUR_API_KEY"

Responses

200Deleted.

{
  "success": true
}

401Missing or invalid API key.Error

{
  "success": false,
  "error": "Invalid API key"
}

404Unknown id.Error

{
  "success": false,
  "error": "File not found"
}

Account

GET

/api/v1/me

Account and quotas

Plan id and upload / storage limits for the API key owner.

Auth: x-api-key · Pro only

Examples

curl -X GET "https://sharable.ryples.com/api/v1/me" \
  -H "x-api-key: sh-YOUR_API_KEY"

Responses

200Account snapshot.Account

{
  "success": true,
  "planId": "pro",
  "maxUploadBytes": 5368709120,
  "maxStorageBytes": 53687091200,
  "usedStorageBytes": 123456
}

401Missing or invalid API key.Error

{
  "success": false,
  "error": "Invalid API key"
}

403Caller is not on Pro.Error

{
  "success": false,
  "error": "API upload is available on Pro. Redeem a code on the pricing page."
}

Spec

GET

/api/v1/openapi.json

OpenAPI document

Machine-readable OpenAPI 3 spec for this API. No API key.

No API key required.

Examples

curl -X GET "https://sharable.ryples.com/api/v1/openapi.json"

Responses

200OpenAPI 3 JSON.

application/json

Schemas

Models

Stable JSON shapes returned by the File API.

FileDetails

Stable public shape for a single API Upload file.

Field	Type	Description
success	boolean	true on success.
id	string	File id.
key	string	Same as id (file.io-style alias).
name	string	Original file name.
link	string	Public share URL at /files/p/{id}.
download	string	Authenticated API download URL.
expires	string \| null	ISO expiry, or null if never.
expiry	string	Duration label such as 7d or never.
downloads	integer	Download count.
maxDownloads	integer	Cap; 0 means unlimited.
autoDelete	boolean	Always true. Expired files are removed by cleanup.
size	integer	Size in bytes.
mimeType	string	Stored MIME type.
created	string	ISO created time.
modified	string	ISO modified time.

{
  "success": true,
  "id": "64f0c2a91b3e4a0012ab34cd",
  "key": "64f0c2a91b3e4a0012ab34cd",
  "name": "report.pdf",
  "link": "https://example.com/files/p/64f0c2a91b3e4a0012ab34cd",
  "download": "https://example.com/api/v1/files/64f0c2a91b3e4a0012ab34cd/download",
  "expires": "2026-08-21T00:00:00.000Z",
  "expiry": "7d",
  "downloads": 0,
  "maxDownloads": 0,
  "autoDelete": true,
  "size": 1234,
  "mimeType": "application/pdf",
  "created": "2026-08-14T00:00:00.000Z",
  "modified": "2026-08-14T00:00:00.000Z"
}

FileList

Paginated list of FileDetails.

Field	Type	Description
success	boolean	true on success.
items	FileDetails[]	Page of files.
offset	integer	Items skipped.
limit	integer	Page size, 1–100.
count	integer	Total matching files (not the page length).

{
  "success": true,
  "items": [
    {
      "success": true,
      "id": "64f0c2a91b3e4a0012ab34cd",
      "key": "64f0c2a91b3e4a0012ab34cd",
      "name": "report.pdf",
      "link": "https://example.com/files/p/64f0c2a91b3e4a0012ab34cd",
      "download": "https://example.com/api/v1/files/64f0c2a91b3e4a0012ab34cd/download",
      "expires": "2026-08-21T00:00:00.000Z",
      "expiry": "7d",
      "downloads": 0,
      "maxDownloads": 0,
      "autoDelete": true,
      "size": 1234,
      "mimeType": "application/pdf",
      "created": "2026-08-14T00:00:00.000Z",
      "modified": "2026-08-14T00:00:00.000Z"
    }
  ],
  "offset": 0,
  "limit": 20,
  "count": 1
}

Account

Plan and quota snapshot for GET /me.

Field	Type	Description
success	boolean	true on success.
planId	string	Effective plan, e.g. pro.
maxUploadBytes	integer	Per-file upload cap.
maxStorageBytes	integer \| null	Account storage quota, or null if unlimited.
usedStorageBytes	integer	Bytes currently stored.

{
  "success": true,
  "planId": "pro",
  "maxUploadBytes": 5368709120,
  "maxStorageBytes": 53687091200,
  "usedStorageBytes": 123456
}

Error

Error envelope for 4xx/5xx JSON responses.

Field	Type	Description
success	boolean	Always false.
error	string	Human-readable message.

{
  "success": false,
  "error": "Invalid API key"
}