Storage Management

The Storage Management endpoints let you list, retrieve, and delete files saved by the curl service. Each saved file is reachable through three symlinked directory layouts — by-job/{uuid}/filename, by-domain/{domain}/{uuid}, and by-date/{YYYY-MM-DD}/{uuid} — so you can locate content using whichever organization best fits your workflow. Use these endpoints to audit downloaded files, find content by source domain or capture date, or clean up old data.

All endpoints on this page are served by the per-container curl instance at https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.com.

Note

All three storage layouts point to the same physical files via symlinks. Deleting a file through any path removes it everywhere.

List saved downloads

GET /api/v1/curl/storage

Returns a paginated list of files saved to storage from HTTP requests. Items are listed under their primary by-job path; the same physical files can also be reached via by-domain and by-date symlinks.

Parameters

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

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);
}

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": 245678,
      "url": "https://api.example.com/report.pdf"
    },
    {
      "created_at": "2024-01-15T11:45:00Z",
      "job_id": "660e8400-e29b-41d4-a716-446655440111",
      "path": "by-domain/api.example.com/660e8400-e29b-41d4-a716-446655440111",
      "size": 89120,
      "url": "https://api.example.com/data.json"
    }
  ],
  "meta": {
    "limit": 50,
    "page": 1,
    "total": 2
  }
}

Each item always exposes path, size, and created_at. When present, job_id is the UUID parsed from the storage path and url is the original source URL. meta carries pagination state.

500

{
  "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}

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

Supported path shapes include:

• by-job/{uuid}/filename (primary)
• by-domain/{domain}/{uuid}
• by-date/{YYYY-MM-DD}/{uuid}

Parameters

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

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>" \
  --output 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 });

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

Response

200

The response body is the raw file bytes returned with Content-Type: application/octet-stream. The spec does not define a JSON body for this status.

404

{
  "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 if the file was deleted

500

{
  "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 deletes a file from storage. This action cannot be undone — the file is removed from all three storage layouts (by-job, by-domain, by-date) at once.

Parameters

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

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.deleteFile('by-job/550e8400-e29b-41d4-a716-446655440000/report.pdf');

Response

200

The delete succeeded. The file is no longer reachable through any of the three storage layouts (by-job, by-domain, by-date). The spec does not define a JSON body for this status.

404

{
  "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 does not exist	Verify the file path using the listStorage endpoint

500

{
  "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