# hoody-curl Subskill ## Overview **hoody-curl** is a service designed to simplify and universalize access to REST APIs by converting complex, multi-step HTTP requests into simple, reusable URLs and commands. It functions as a powerful proxy and job scheduler, allowing AI agents and users to execute HTTP requests synchronously or asynchronously, manage cookie sessions, schedule recurring tasks, and store responses—all through the Hoody CLI. **When to Use It:** - When you need to call an external or internal REST API but want to abstract away complex headers, authentication, or request bodies. - To run HTTP requests in the background (as jobs) and retrieve results later. - To set up recurring API calls on a schedule (cron). - To maintain stateful interactions by managing cookie sessions across multiple requests. - To automatically save API responses or downloads to persistent storage. **How It Fits into Hoody Philosophy:** hoody-curl embodies the "GET-ify any REST API" principle. It provides a unified CLI (`hoody curl`) that abstracts HTTP verbs, complex payloads, and execution modes into simple, declarative commands. This allows any agent to interact with web services without needing to manage low-level details, promoting universal access and reusable automation. --- ## Common Workflows ### 1. Execute a Simple HTTP Request Use the GET-based request for simple queries or testing. ``` # Execute a simple GET request hoody curl get-url "https://httpbin.org/get" -c my-container-id -o json ``` ``` { "args": {}, "headers": { "Host": "httpbin.org" }, "origin": "123.45.67.89", "url": "https://httpbin.org/get" } ``` ### 2. Execute a Complex HTTP Request (POST with Body) Use the `exec` command for advanced requests with methods, headers, and bodies. ``` # Execute a POST request with a JSON body hoody curl exec \ -c my-container-id \ --method POST \ --url "https://httpbin.org/post" \ --header "Content-Type: application/json" \ --body '{"key": "value"}' \ -o json ``` ``` { "data": "{\"key\": \"value\"}", "json": { "key": "value" }, "url": "https://httpbin.org/post" } ``` ### 3. Run an Asynchronous Job and Retrieve Results Execute a request in the background and poll for completion. ``` # Start an async job hoody curl exec \ -c my-container-id \ --url "https://httpbin.org/delay/5" \ --async \ -o json ``` ``` { "id": "job_123abc", "status": "pending", "name": "GET https://httpbin.org/delay/5" } ``` ``` # Check job status hoody curl get job_123abc -c my-container-id -o json ``` ``` { "id": "job_123abc", "status": "completed", "response": { "url": "https://httpbin.org/delay/5" } } ``` ``` # Get the job's response body directly hoody curl result job_123abc -c my-container-id -o json ``` ``` { "url": "https://httpbin.org/delay/5" } ``` ### 4. Create and Manage a Recurring Schedule Set up a cron job to call an API every minute. ``` # Create a new schedule hoody curl create \ -c my-container-id \ --cron "0 * * * * *" \ --request '{"method": "GET", "url": "https://httpbin.org/get"}' \ -o json ``` ``` { "id": "schedule_xyz789", "cron": "0 * * * * *", "next_execution": "2025-11-05T12:01:00Z", "enabled": true } ``` ``` # List all schedules hoody curl list -c my-container-id -o json ``` ``` [ { "id": "schedule_xyz789", "cron": "0 * * * * *", "next_execution": "2025-11-05T12:01:00Z", "enabled": true } ] ``` ``` # Temporarily disable the schedule hoody curl toggle schedule_xyz789 -c my-container-id -o json ``` ``` { "id": "schedule_xyz789", "enabled": false } ``` ### 5. Use Sessions for Stateful Interactions (e.g., Authentication) Log in to a website and use the preserved cookies for subsequent requests. ``` # Execute a login request (cookies are automatically captured) hoody curl exec \ -c my-container-id \ --method POST \ --url "https://httpbin.org/post" \ --header "Content-Type: application/x-www-form-urlencoded" \ --body "username=user&password=pass" \ -o json ``` ``` { "form": { "password": "pass", "username": "user" }, "url": "https://httpbin.org/post" } ``` ``` # List sessions to find the one with cookies hoody curl list -c my-container-id -o json ``` ``` [ { "id": "session_abc123", "last_used": "2025-11-05T12:00:00Z" } ] ``` ``` # Use the session for a protected request hoody curl exec \ -c my-container-id \ --url "https://httpbin.org/cookies" \ --session session_abc123 \ -o json ``` ``` { "cookies": { "session_id": "abc123" } } ``` ### 6. Monitor Jobs with Real-Time Events Subscribe to job lifecycle events over WebSocket or SSE. ``` # Subscribe to job events via SSE hoody curl events -c my-container-id --format sse ``` ``` event: jobstarted data: {"job_id": "job_123abc", "name": "GET https://httpbin.org/get"} event: jobcompleted data: {"job_id": "job_123abc", "status": "completed"} ``` --- ## Advanced Operations ### 1. Multi-Step Workflow: Scrape a Website with Login Combine sessions, jobs, and storage to log in and download a protected resource. ``` # Step 1: Login and capture session cookies SESSION_ID=$(hoody curl exec \ -c my-container-id \ --method POST \ --url "https://httpbin.org/post" \ --header "Content-Type: application/x-www-form-urlencoded" \ --body "username=user&password=pass" \ -o json | jq -r '.id') ``` ``` # Step 2: Use the session to download a file (async job) JOB_ID=$(hoody curl exec \ -c my-container-id \ --url "https://httpbin.org/image/png" \ --session $SESSION_ID \ --async \ -o json | jq -r '.id') ``` ``` # Step 3: Poll job until completed hoody curl get $JOB_ID -c my-container-id -o json ``` ``` { "id": "job_456def", "status": "completed" } ``` ``` # Step 4: List the downloaded file in storage hoody curl list -c my-container-id -o json ``` ``` [ { "path": "by-job/job_456def/image.png", "size": 1234 } ] ``` ### 2. Error Recovery: Retry Failed Jobs Monitor jobs and restart them if they fail. ``` # List jobs and filter for failed ones FAILED_JOB=$(hoody curl list -c my-container-id -o json | jq '.[] | select(.status == "failed") | .id') ``` ``` # Re-execute the failed job's request hoody curl exec \ -c my-container-id \ --url "https://httpbin.org/status/500" \ -o json ``` ### 3. Performance: Bulk Request with Parallel Async Jobs Launch multiple independent requests in parallel as background jobs. ``` # Launch three async jobs for i in 1 2 3; do hoody curl exec \ -c my-container-id \ --url "https://httpbin.org/delay/$i" \ --async \ -o json done ``` ``` # Monitor all jobs hoody curl list -c my-container-id -o json ``` ``` [ { "id": "job_1", "status": "running" }, { "id": "job_2", "status": "pending" }, { "id": "job_3", "status": "pending" } ] ``` ### 4. Debugging: Inspect Request Details and Responses Use the job details endpoint to debug execution issues. ``` # Get detailed job info including request configuration hoody curl get job_123abc -c my-container-id -o json ``` ``` { "id": "job_123abc", "status": "completed", "request": { "method": "GET", "url": "https://httpbin.org/delay/5" }, "response": { "status_code": 200, "body": "{\"url\": \"https://httpbin.org/delay/5\"}" } } ``` ### 5. Cleanup: Delete Old Jobs and Storage Maintain system hygiene by removing old data. ``` # Delete a specific job hoody curl delete job_123abc -c my-container-id --yes ``` ``` # Delete a file from storage hoody curl delete by-job/job_123abc/response.json -c my-container-id --yes ``` ``` # Delete a session hoody curl delete session_abc123 -c my-container-id --yes ``` --- ## Quick Reference ### Essential Commands | Task | Command | |------|---------| | **Health Check** | `hoody curl health -c ` | | **Execute GET Request** | `hoody curl get-url "URL" -c -o json` | | **Execute Advanced Request** | `hoody curl exec -c --url "URL" [OPTIONS]` | | **List Jobs** | `hoody curl list -c -o json` | | **Get Job Details** | `hoody curl get -c -o json` | | **Get Job Result** | `hoody curl result -c -o json` | | **Cancel Job** | `hoody curl cancel -c ` | | **Create Schedule** | `hoody curl create -c --cron "EXPRESSION" --request '{...}'` | | **List Schedules** | `hoody curl list -c -o json` | | **Toggle Schedule** | `hoody curl toggle -c ` | | **List Sessions** | `hoody curl list -c -o json` | | **Get Session Cookies** | `hoody curl cookies -c -o json` | | **List Stored Files** | `hoody curl list -c -o json` | | **Download File** | `hoody curl get -c ` | | **Subscribe to Events** | `hoody curl events -c [--format sse]` | | **Get Metrics** | `hoody curl metrics -c ` | ### Key Parameters - `-c `: **Required** for all commands targeting a container. - `-o json`: Output in JSON format (recommended for machine processing). - `--async`: Run request as background job. - `--session `: Use a cookie session for the request. - `--method `: HTTP method (GET, POST, PUT, DELETE, etc.). - `--header "Key: Value"`: Add request headers. - `--body '...'`: Request body (for POST/PUT/PATCH). - `--cron "EXPRESSION"`: 6-field cron expression (second minute hour day month weekday). - `--yes`: Skip confirmation prompts for delete operations. ### Typical Response Structures **Job Response:** ``` { "id": "string", "status": "pending|running|completed|failed|cancelled", "request": {}, "response": {}, "created_at": "timestamp", "completed_at": "timestamp" } ``` **Schedule Response:** ``` { "id": "string", "cron": "string", "request": {}, "enabled": true, "next_execution": "timestamp" } ``` **Session Response:** ``` { "id": "string", "last_used": "timestamp", "cookies": [] } ``` ### State Verification - After executing an async job, always check status with `hoody curl get `. - Verify schedule creation with `hoody curl list` and check `next_execution`. - Confirm session cookies are present with `hoody curl cookies ` before making authenticated requests.