<!--
hoody-curl Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-05-06T18:31:10.970Z
Model: mimo-v2.5-pro + fixer:mimo-v2.5-pro
Mode: http


Tokens: 6748

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-curl Subskill

## Overview

**hoody-curl** is a universal HTTP proxy service that "GET-ifies" any REST API for universal access. It proxies complex API calls through simple URLs, enabling authenticated HTTP requests, scheduled jobs, persistent sessions, and file storage—all accessible via a single service endpoint.

### When to Use hoody-curl

- **API Proxying**: Execute HTTP requests to external APIs without exposing credentials in client code
- **Scheduled Requests**: Create cron-based recurring HTTP requests (health checks, data syncs, webhooks)
- **Async Jobs**: Submit long-running HTTP requests as background jobs with progress tracking
- **Session Management**: Maintain cookie-based sessions for multi-step authentication flows
- **File Storage**: Save HTTP response bodies to persistent storage for later retrieval
- **WebSocket Events**: Monitor job lifecycle events in real-time via WebSocket

### How It Fits Hoody Philosophy

hoody-curl embodies "GET-ify any REST API for universal access." Complex POST/PUT/DELETE operations to external services become accessible through a unified proxy. Combined with Hoody's automatic routing, authentication, and SSL termination, any containerized workflow can interact with external APIs securely.

### Service Discovery

Use the Hoody Kit service URL pattern:

```
https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu
```

Refer to the core SKILL.md for container creation and service discovery. Do NOT use `api.hoody.com` for hoody-curl endpoints.

---

## Common Workflows

### 1. Execute a Simple GET Request

The quickest way to proxy an external API call:

```
# Using query parameters for simple GET requests
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/request?url=https://api.example.com/data"
```

### 2. Execute a Full HTTP Request (POST)

For advanced requests with headers, body, and method control:

```
curl -s -X POST \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/request" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhook",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer token123"
    },
    "body": "{\"event\": \"test\"}"
  }'
```

### 3. Submit an Async Job

For long-running requests, use async mode:

```
# Submit async job
curl -s -X POST \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/request" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/large-export",
    "mode": "async"
  }'
```

Response includes a `job_id`. Check job status:

```
# Check job status
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/jobs/{job_id}"
```

Retrieve result when complete:

```
# Get job result
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/jobs/{job_id}/result"
```

### 4. List and Manage Jobs

```
# List all jobs (newest first)
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/jobs"

# Cancel a pending/running job
curl -s -X DELETE \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/jobs/{job_id}"
```

### 5. Create a Scheduled Request

Set up a recurring HTTP request with cron scheduling:

```
curl -s -X POST \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/schedule" \
  -H "Content-Type: application/json" \
  -d '{
    "cron": "0 */5 * * * *",
    "request": {
      "url": "https://api.example.com/health-check"
    }
  }'
```

**Cron Format**: 6 fields — `second minute hour day month weekday`

### 6. Manage Schedules

```
# List all schedules
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/schedule"

# Get schedule details
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/schedule/{schedule_id}"

# Toggle schedule on/off
curl -s -X PATCH \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/schedule/{schedule_id}/toggle" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Delete schedule
curl -s -X DELETE \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/schedule/{schedule_id}"
```

### 7. Session-Based Cookie Management

For multi-step authentication flows that require cookie persistence:

```
# List active sessions
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/sessions"

# Get session details with cookies
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/sessions/{session_id}"

# Get only cookies from a session
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/sessions/{session_id}/cookies"

# Delete a session
curl -s -X DELETE \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/sessions/{session_id}"
```

### 8. File Storage Operations

```
# List all stored files
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/storage"

# Retrieve a stored file
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/storage/{path}"

# Delete a stored file
curl -s -X DELETE \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/storage/{path}"
```

### 9. Check Service Health

Verify the service is running and responsive:

```
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/health"
```

This should return a JSON response indicating service status.

### 10. Monitor Prometheus Metrics

Access exported metrics for monitoring request counts, latency, and job queue size:

```
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/metrics"
```

The response is in Prometheus format, which can be scraped by monitoring tools.

---

## Advanced Operations

### Multi-Step Authenticated Workflow

Combine sessions with requests for stateful API interactions:

```
# Step 1: Login request (cookies auto-captured in session)
curl -s -X POST \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/request" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/login",
    "method": "POST",
    "body": "{\"username\": \"user\", \"password\": \"pass\"}",
    "session": "my-auth-session"
  }'

# Step 2: Use authenticated session for subsequent requests
curl -s -X POST \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/request" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/protected-resource",
    "session": "my-auth-session"
  }'

# Step 3: Verify session cookies
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/sessions/my-auth-session/cookies"
```

### Async Job with File Storage

Save large response bodies to storage for later retrieval:

```
# Submit job with storage enabled
curl -s -X POST \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/request" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/large-dataset",
    "mode": "async",
    "save": true
  }'

# Monitor job progress
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/jobs/{job_id}"

# List storage to find saved file
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/storage"
```

### Real-Time Job Monitoring via WebSocket

Connect to the WebSocket endpoint for live job events:

```
// WebSocket connection for job lifecycle events
const ws = new WebSocket(
  "wss://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/ws"
);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // Events: jobstarted, jobprogress, jobcompleted, jobfailed
  console.log(data);
};
```

### Error Recovery Patterns

**Job stuck in pending state:**

```
# Check job details for error info
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/jobs/{job_id}"

# Cancel and resubmit if needed
curl -s -X DELETE \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/jobs/{job_id}"
```

**Schedule not executing:**

```
# Check schedule status
curl -s \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/schedule/{schedule_id}"

# Ensure schedule is enabled
curl -s -X PATCH \
  "https://{projectId}-{containerId}-curl-{serviceId}.{node}.containers.hoody.icu/api/v1/curl/schedule/{schedule_id}/toggle" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

### Performance Considerations

- **Timeouts**: Always set `` on curl commands to prevent hanging connections
- **Async for long requests**: Use `mode: "async"` for requests that may take >30 seconds
- **Session reuse**: Reuse sessions instead of creating new ones for authenticated flows
- **Storage cleanup**: Periodically delete unused files from storage to conserve space
- **Job cleanup**: Cancel or delete completed jobs to maintain clean job lists

---

## Quick Reference

### Health & Monitoring

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/curl/health` | GET | Service health check (unauthenticated) |
| `/metrics` | GET | Prometheus metrics export (see workflow 10 for example) |

### Core Request Execution

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/curl/request` | GET | Simple request via query params |
| `/api/v1/curl/request` | POST | Full request with body/headers |

### Job Management

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/curl/jobs` | GET | List all async jobs |
| `/api/v1/curl/jobs/{id}` | GET | Get job details |
| `/api/v1/curl/jobs/{id}` | DELETE | Cancel job |
| `/api/v1/curl/jobs/{id}/result` | GET | Get job response body |

### Schedule Management

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/curl/schedule` | GET | List all schedules |
| `/api/v1/curl/schedule` | POST | Create schedule |
| `/api/v1/curl/schedule/{id}` | GET | Get schedule details |
| `/api/v1/curl/schedule/{id}` | DELETE | Delete schedule |
| `/api/v1/curl/schedule/{id}/toggle` | PATCH | Enable/disable schedule |

### Session Management

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/curl/sessions` | GET | List all sessions |
| `/api/v1/curl/sessions/{id}` | GET | Get session details |
| `/api/v1/curl/sessions/{id}` | DELETE | Delete session |
| `/api/v1/curl/sessions/{id}/cookies` | GET | Get session cookies |

### Storage

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/curl/storage` | GET | List stored files |
| `/api/v1/curl/storage/{path}` | GET | Retrieve file |
| `/api/v1/curl/storage/{path}` | DELETE | Delete file |

### Real-Time Events

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/curl/ws` | GET | WebSocket for job events |

### Essential Parameters

**POST /api/v1/curl/request** (required: `url`):
- `url` (string): Target URL
- `method` (string): HTTP method (default: GET)
- `headers` (object): Request headers
- `body` (string): Request body
- `mode` (string): "sync" or "async"
- `session` (string): Session name for cookie persistence
- `save` (boolean): Save response to storage

**POST /api/v1/curl/schedule** (required: `cron`, `request`):
- `cron` (string): 6-field cron expression
- `request` (object): Contains required `request.url` (string)

**WebSocket Connection**: For real-time job events, see the Real-Time Job Monitoring via WebSocket example in Advanced Operations.