Storage Management

The storage endpoints let you list, retrieve, and delete files that have been saved to disk by the curl service. Saved files are organized under three symlinked directory structures — by-job, by-domain, and by-date — so the same physical file can be referenced through any of the three paths. Use these endpoints to audit downloads, look up files by domain or date, or clean up old content.

List saved downloads

`GET /api/v1/curl/storage`

Retrieve a paginated list of every file currently saved to storage. Each entry includes its relative path, byte size, creation timestamp, and the originating job UUID when one can be parsed from the path. Files appear under their by-job, by-domain, and by-date paths, but all three resolve to the same physical file.

Parameters

Name	In	Type	Required	Description
`page`	query	integer	No	1-based page number
`limit`	query	integer	No	Items per page. When omitted, the handler returns all items.

curl -X GET "https://proj-abc123-cont-curl-1.eu-west-1.containers.hoody.icu/api/v1/curl/storage?page=1&limit=20" \
  -H "Authorization: Bearer <token>"

await client.curl.storage.listIterator({ page: 1, limit: 20 });

{
  "items": [
    {
      "path": "by-job/550e8400-e29b-41d4-a716-446655440000/report.pdf",
      "size": 184320,
      "created_at": "2024-01-15T14:22:10.000Z",
      "job_id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://api.example.com/reports/q4.pdf"
    },
    {
      "path": "by-domain/api.example.com/660e8400-e29b-41d4-a716-446655440111",
      "size": 9216,
      "created_at": "2024-01-15T15:03:48.000Z",
      "job_id": "660e8400-e29b-41d4-a716-446655440111",
      "url": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

{
  "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 that the storage directory exists and has read permissions

Download a saved file

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

Stream the raw contents of a previously saved file. The response uses Content-Type: application/octet-stream, so it works for any file type. The path parameter accepts any of the three symlinked forms (by-job/..., by-domain/..., or by-date/...).

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)

curl -X GET "https://proj-abc123-cont-curl-1.eu-west-1.containers.hoody.icu/api/v1/curl/storage/by-job/550e8400-e29b-41d4-a716-446655440000/report.pdf" \
  -H "Authorization: Bearer <token>" \
  --output report.pdf

await client.curl.storage.getFile("by-job/550e8400-e29b-41d4-a716-446655440000/report.pdf");

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 184320

<binary file contents>

{
  "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 the file path using `listStorage`, and check whether the 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 a saved file

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

Permanently delete a file from storage. This action cannot be undone. Deleting a file removes only the underlying physical file — any other symlinked paths pointing to it will subsequently return 404.

Parameters

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

curl -X DELETE "https://proj-abc123-cont-curl-1.eu-west-1.containers.hoody.icu/api/v1/curl/storage/by-job/550e8400-e29b-41d4-a716-446655440000/report.pdf" \
  -H "Authorization: Bearer <token>"

await client.curl.storage.deleteFile("by-job/550e8400-e29b-41d4-a716-446655440000/report.pdf");

{
  "success": true
}

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

Error Code	Title	Description	Resolution
`FILE_NOT_FOUND`	File does not exist	Cannot delete a file that doesn’t exist	Verify the file path using the `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 the operation