REST API Reference
Base URL: https://api.nomiastorage.com/v1
Authentication
All API requests must include a bearer token in the Authorization header. You can generate API keys from your workspace settings. Keys are workspace-scoped and can be granted read-only or read-write access.
curl https://api.nomiastorage.com/v1/files \ -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx"
API keys are prefixed sk_live_ for production and sk_test_ for sandbox. Test keys are rate-limited but free to use.
Rate limits
Rate limits apply per API key. When a limit is exceeded the API returns HTTP 429 with a Retry-After header indicating when you can retry.
| Plan | Read operations | Write operations | Upload throughput |
|---|---|---|---|
| Starter | 300 req/min | 60 req/min | 1 GB/hr |
| Pro | 1,200 req/min | 300 req/min | 10 GB/hr |
| Business | 6,000 req/min | 1,200 req/min | 100 GB/hr |
| Enterprise | Custom | Custom | Custom |
Errors
All errors follow a consistent JSON shape. The code field is machine-readable; message is for humans.
{
"error": {
"code": "file_not_found",
"message": "No file with id 'fil_xyz' exists in this workspace.",
"request_id": "req_01hxyz..."
}
}Files
| Method | Path | Description |
|---|---|---|
| GET | /files | List files in a workspace or folder |
| POST | /files | Initiate a multipart upload |
| GET | /files/{id} | Retrieve file metadata |
| GET | /files/{id}/content | Download file content |
| PUT | /files/{id} | Update file name or metadata |
| DELETE | /files/{id} | Delete a file (moved to trash) |
| POST | /files/{id}/copy | Copy a file to another folder |
Folders
| Method | Path | Description |
|---|---|---|
| GET | /folders | List top-level folders |
| POST | /folders | Create a folder |
| GET | /folders/{id} | Get folder metadata and contents |
| PUT | /folders/{id} | Rename or move a folder |
| DELETE | /folders/{id} | Delete a folder and its contents |
Webhooks
Nomia delivers signed POST requests to your endpoint when events occur. Verify the Nomia-Signature header to authenticate each delivery.
| Method | Path | Description |
|---|---|---|
| GET | /webhooks | List registered webhook endpoints |
| POST | /webhooks | Register a new webhook endpoint |
| DELETE | /webhooks/{id} | Delete a webhook endpoint |
Client libraries
Official SDKs are maintained by Nomia and kept in sync with the API. All are open-source under MIT.