Storage Management

The Storage Management endpoints let you list, retrieve, and delete files saved to storage from HTTP requests. Files are organized in three directory structures that all 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.

Note

All three directory structures point to the same physical files via symlinks, so listing or deleting a file through any of the three paths affects the same underlying data.

List all saved downloads

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

GET /api/v1/curl/storage

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)

Response

200

{
  "items": [
    {
      "created_at": "2024-01-15T10:30:00Z",
      "job_id": "550e8400-e29b-41d4-a716-446655440000",
      "path": "by-job/550e8400-e29b-41d4-a716-446655440000/report.pdf",
      "size": 1048576,
      "url": "https://reports.example.com/daily.pdf"
    },
    {
      "created_at": "2024-01-15T09:15:00Z",
      "job_id": "660e8400-e29b-41d4-a716-446655440111",
      "path": "by-domain/api.example.com/660e8400-e29b-41d4-a716-446655440111",
      "size": 524288,
      "url": "https://api.example.com/data.json"
    }
  ],
  "meta": {
    "limit": 50,
    "page": 1,
    "total": 2
  }
}

400

{
  "code": "INVALID_PARAMETER",
  "error": "Invalid request: timeout must be <= 7200"
}

Error Code	Title	Description	Resolution
INVALID_PARAMETER	Invalid request	A parameter, query value or JSON body is missing, malformed or out of range	Check the message for the offending field and fix the request; retrying unchanged fails again

403

{
  "code": "ORIGIN_NOT_ALLOWED",
  "error": "Origin not allowed"
}

Error Code	Title	Description	Resolution
ORIGIN_NOT_ALLOWED	Origin rejected	The server runs in origin-list CORS mode and the request’s Origin header is not on the list; the request is refused before it reaches a handler	Call from an allowed origin, or add the origin to the server’s --cors list

500

{
  "code": "STORAGE_ERROR",
  "error": "IO error: No space left on device (os error 28)"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage failure	Reading or writing the service’s storage directory failed	Retry; check the storage directory’s permissions and free space if it persists
INTERNAL_ERROR	Service-side failure	The service itself failed (a corrupt record, a worker join, shutdown in progress)	Retry; check the server logs if it persists

Example request

cURL

curl -X GET "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com/api/v1/curl/storage?page=1&limit=50" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

for await (const item of client.curl.storage.listIterator({ page: 1, limit: 50 })) {
  console.log(item);
}

Download a saved file

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

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

The {path} parameter accepts any of the three directory structures. 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)

Response

200

The response body is the raw file content as a binary stream, served with Content-Type: application/octet-stream. The body is not JSON.

403

{
  "code": "ORIGIN_NOT_ALLOWED",
  "error": "Origin not allowed"
}

Error Code	Title	Description	Resolution
ORIGIN_NOT_ALLOWED	Origin rejected	The server runs in origin-list CORS mode and the request’s Origin header is not on the list; the request is refused before it reaches a handler	Call from an allowed origin, or add the origin to the server’s --cors list

404

{
  "code": "FILE_NOT_FOUND",
  "error": "Storage not found: by-job/550e8400-e29b-41d4-a716-446655440000/data.bin"
}

Error Code	Title	Description	Resolution
FILE_NOT_FOUND	File does not exist	No saved download exists at this storage path	List saved files with listStorage

500

{
  "code": "STORAGE_ERROR",
  "error": "IO error: No space left on device (os error 28)"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage failure	Reading or writing the service’s storage directory failed	Retry; check the storage directory’s permissions and free space if it persists
INTERNAL_ERROR	Service-side failure	The service itself failed (a corrupt record, a worker join, shutdown in progress)	Retry; check the server logs if it persists

400

Error Code	Title	Description	Resolution
INVALID_PARAMETER	Invalid request	A parameter, query value or JSON body is missing, malformed or out of range	Check the message for the offending field and fix the request; retrying unchanged fails again

Example request

cURL

curl -X GET "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com/api/v1/curl/storage/by-job/550e8400-e29b-41d4-a716-446655440000/report.pdf" \
  -H "Authorization: Bearer <token>" \
  -o report.pdf

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Delete a saved file

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

Caution

Deletion is permanent and cannot be undone. All three symlinked paths (by-job, by-domain, by-date) point to the same physical file, so deleting through any path removes the file entirely.

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

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Relative path to file in storage
recursive	query	boolean	No	true deletes a directory and everything in it (default false)

Response

200

File deleted successfully.

403

{
  "code": "ORIGIN_NOT_ALLOWED",
  "error": "Origin not allowed"
}

Error Code	Title	Description	Resolution
ORIGIN_NOT_ALLOWED	Origin rejected	The server runs in origin-list CORS mode and the request’s Origin header is not on the list; the request is refused before it reaches a handler	Call from an allowed origin, or add the origin to the server’s --cors list

404

{
  "code": "FILE_NOT_FOUND",
  "error": "Storage not found: by-job/550e8400-e29b-41d4-a716-446655440000/data.bin"
}

Error Code	Title	Description	Resolution
FILE_NOT_FOUND	File does not exist	No saved download exists at this storage path	List saved files with listStorage

500

{
  "code": "STORAGE_ERROR",
  "error": "IO error: No space left on device (os error 28)"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage failure	Reading or writing the service’s storage directory failed	Retry; check the storage directory’s permissions and free space if it persists
INTERNAL_ERROR	Service-side failure	The service itself failed (a corrupt record, a worker join, shutdown in progress)	Retry; check the server logs if it persists

400

Error Code	Title	Description	Resolution
INVALID_PARAMETER	Invalid request	A parameter, query value or JSON body is missing, malformed or out of range	Check the message for the offending field and fix the request; retrying unchanged fails again

Example request

cURL

curl -X DELETE "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com/api/v1/curl/storage/by-job/550e8400-e29b-41d4-a716-446655440000/report.pdf" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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