Storage Management

List, retrieve, and delete files saved to storage from HTTP requests. Files are organized in three interchangeable directory structures that point to the same physical files via symlinks:

by-job/{uuid}/filename — Primary location, organized by storage UUID
by-domain/{domain}/{uuid} — Grouped by source domain
by-date/{YYYY-MM-DD}/{uuid} — Grouped by download date

Use these endpoints to audit downloaded files, find files by domain or date, or clean up old downloads.

`GET /api/v1/curl/storage`

Retrieve a list of all files saved to storage from HTTP requests.

Parameters

Name	In	Type	Required	Description
`page`	query	integer	No	1-based page number
`limit`	query	integer	No	Items per page (current handler returns all items when omitted)

This endpoint accepts no request body.

curl -X GET "https://api.hoody.com/api/v1/curl/storage?page=1&limit=20" \
  -H "Authorization: Bearer <token>"

const iterator = await client.curl.storage.listIterator({ page: 1, limit: 20 });
for await (const entry of iterator) {
  console.log(entry.path, entry.size);
}

{
  "items": [
    {
      "path": "by-job/550e8400-e29b-41d4-a716-446655440000/report.pdf",
      "size": 102400,
      "created_at": "2024-01-15T10:30:00Z",
      "job_id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://api.example.com/report.pdf"
    },
    {
      "path": "by-date/2024-01-15/660e8400-e29b-41d4-a716-446655440111",
      "size": 51200,
      "created_at": "2024-01-15T11:45:00Z",
      "job_id": "660e8400-e29b-41d4-a716-446655440111",
      "url": "https://cdn.example.com/data.json"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20
  }
}

{
  "error": "STORAGE_ERROR",
  "message": "Failed to read storage directory"
}

Error Code	Title	Description	Resolution
`STORAGE_ERROR`	Storage read failed	Unable to read storage directory or file metadata	Check storage directory exists and has read permissions

`GET /api/v1/curl/storage/{path}`

Retrieve the contents of a file previously saved to storage. The file is returned with Content-Type: application/octet-stream, making it suitable for downloads of any file type.

Path examples:

by-job/550e8400-e29b-41d4-a716-446655440000/report.pdf
by-domain/api.example.com/660e8400-e29b-41d4-a716-446655440111
by-date/2024-01-15/770e8400-e29b-41d4-a716-446655440222

Parameters

Name	In	Type	Required	Description
`path`	path	string	Yes	Relative path to file in storage (supports nested paths)

This endpoint accepts no request body.

curl -X GET "https://api.hoody.com/api/v1/curl/storage/by-job/550e8400-e29b-41d4-a716-446655440000/report.pdf" \
  -H "Authorization: Bearer <token>" \
  --output report.pdf

const stream = await client.curl.storage.getFile({
  path: "by-job/550e8400-e29b-41d4-a716-446655440000/report.pdf"
});

Binary file content (Content-Type: application/octet-stream)

{
  "error": "FILE_NOT_FOUND",
  "message": "File not found"
}

Error Code	Title	Description	Resolution
`FILE_NOT_FOUND`	File does not exist	No file exists at the specified storage path	Verify file path using listStorage, check if file was deleted

{
  "error": "FILE_READ_ERROR",
  "message": "Failed to read file"
}

Error Code	Title	Description	Resolution
`FILE_READ_ERROR`	File read failed	File exists but cannot be read	Check file permissions and disk integrity

`DELETE /api/v1/curl/storage/{path}`

Permanently delete a file from storage. This action cannot be undone.

Parameters

Name	In	Type	Required	Description
`path`	path	string	Yes	Relative path to file in storage

This endpoint accepts no request body.

curl -X DELETE "https://api.hoody.com/api/v1/curl/storage/by-date/2024-01-15/770e8400-e29b-41d4-a716-446655440222" \
  -H "Authorization: Bearer <token>"

await client.curl.storage.deleteFile({
  path: "by-date/2024-01-15/770e8400-e29b-41d4-a716-446655440222"
});

HTTP/1.1 200 OK

File deleted successfully. No response body.

{
  "error": "FILE_NOT_FOUND",
  "message": "File not found"
}

Error Code	Title	Description	Resolution
`FILE_NOT_FOUND`	File does not exist	Cannot delete file that doesn’t exist	Verify file path using listStorage endpoint

{
  "error": "FILE_DELETE_ERROR",
  "message": "Failed to delete file"
}

Error Code	Title	Description	Resolution
`FILE_DELETE_ERROR`	File deletion failed	File exists but could not be deleted	Check file permissions and retry operation