Complete reference for all REST endpoints. All paths are relative to /api/v1.
Endpoints for account creation and API key lifecycle.
/api/v1/users/registerCreate a new user account. Returns the generated API key — it is shown only once.
Request Body
{
"email": "user@example.com",
"password": "securePassword123"
}Response
{
"status": 201,
"message": "User registered successfully",
"data": {
"email": "user@example.com",
"api_key": "ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"created_at": "2026-03-14T12:00:00Z"
}
}/api/v1/users/renew/challengeRequest a key-renewal verification code. The code is sent to the account's registered email.
Request Body
{
"email": "user@example.com"
}Response
{
"status": 200,
"message": "Verification code sent to email"
}/api/v1/users/renewComplete the renewal flow using the verification code. Returns a new API key.
Request Body
{
"email": "user@example.com",
"verification_code": "123456"
}Response
{
"status": 200,
"message": "API key renewed successfully",
"data": {
"api_key": "ak_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}
}/api/v1/users/status🔑 requires API keyReturn the authenticated user's account status and metadata.
Response
{
"status": 200,
"data": {
"email": "user@example.com",
"created_at": "2026-03-14T12:00:00Z",
"file_count": 42,
"total_size_bytes": 10485760
}
}Upload, retrieve, list, delete, pin, and unpin files on IPFS.
/api/v1/files/upload🔑 requires API keyUpload a file as multipart/form-data. Returns the file's IPFS CID and metadata.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| file | formData | yes | binary | The file to upload |
Response
{
"status": 201,
"message": "File uploaded successfully",
"data": {
"cid": "bafkreih5aznjvttude6c3wbvqeebb6rlx7kibuzn7i56aklrbb2a5v53em",
"original_filename": "report.pdf",
"size": 204800,
"content_type": "application/pdf",
"pinned": true,
"uploaded_at": "2026-03-14T12:00:00Z"
}
}/api/v1/files/retrieve/{cid}🔑 requires API keyRetrieve (stream) a file by its CID. Responds with the file bytes and sets Content-Type.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| cid | path | yes | string | IPFS Content Identifier |
Response
<binary file content with appropriate Content-Type header>/api/v1/files🔑 requires API keyList all files uploaded by the authenticated user.
Response
{
"status": 200,
"data": [
{
"cid": "bafkreih5...",
"original_filename": "report.pdf",
"size": 204800,
"pinned": true,
"uploaded_at": "2026-03-14T12:00:00Z"
}
]
}/api/v1/files/{cid}🔑 requires API keyDelete a single file by CID. Unpins and removes metadata.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| cid | path | yes | string | IPFS Content Identifier |
Response
{
"status": 200,
"message": "File deleted successfully"
}/api/v1/files/delete/bulk🔑 requires API keyDelete multiple files in a single request.
Request Body
{
"cids": [
"bafkreih5...",
"bafkreih6..."
]
}Response
{
"status": 200,
"message": "Files deleted successfully",
"data": {
"deleted": 2,
"failed": []
}
}/api/v1/files/{cid}/pin🔑 requires API keyPin a file on IPFS to ensure it remains available.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| cid | path | yes | string | IPFS Content Identifier |
Response
{
"status": 200,
"message": "File pinned successfully"
}/api/v1/files/{cid}/unpin🔑 requires API keyUnpin a file from IPFS. The content may eventually be garbage-collected.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| cid | path | yes | string | IPFS Content Identifier |
Response
{
"status": 200,
"message": "File unpinned successfully"
}Long-running operations (e.g. bulk deletes, background pin jobs) are handled by Celery tasks. Poll the status endpoint to track progress.
/api/v1/tasks/{task_id}/status🔑 requires API keyReturn the current status of an async Celery task.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_id | path | yes | string | UUID returned when the task was started |
Response
{
"status": 200,
"data": {
"task_id": "d4a2c6f8-...",
"state": "SUCCESS",
"result": { "deleted": 3 },
"created_at": "2026-03-14T12:00:00Z",
"completed_at": "2026-03-14T12:00:05Z"
}
}Task States
state values: PENDING, STARTED, SUCCESS, FAILURE, REVOKED.All error responses share the same envelope shape:
{
"status": 400,
"error": "Bad Request",
"message": "Human-readable description of what went wrong"
}| Code | Name | When it occurs |
|---|---|---|
| 400 | Bad Request | Malformed JSON, missing required fields, invalid file type or size |
| 401 | Unauthorized | Missing or invalid X-API-Key header |
| 403 | Forbidden | Account suspended or key invalidated |
| 404 | Not Found | CID or resource does not exist for this user |
| 409 | Conflict | Duplicate registration email or file already pinned |
| 422 | Unprocessable Entity | Validation passed but business logic rejected the request |
| 429 | Too Many Requests | Rate limit exceeded; check Retry-After header |
| 500 | Internal Server Error | Unexpected server-side error; contact support |