Perpetua Skill (Hosted)

---

name: perpetua

description: "OAuth proxy for calling external APIs (Oura, Google Calendar, etc.) via Perpetua.sh hosted API using a single API key. Use when fetching Oura data, Google Calendar events, or managing OAuth connections."

version: "1.0.0"

read_when:

- User asks about Oura Ring data (sleep, readiness, activity, workouts, HRV)

- User asks about Google Calendar events or schedule

- User wants to add or manage OAuth provider connections

- Perpetua proxy setup or troubleshooting

- User asks what's on their calendar or how they slept

triggers:

- oura

- sleep score

- readiness score

- hrv

- perpetua

- oauth proxy

- calendar

- google calendar

metadata:

{

"openclaw":

{

"emoji": "🔑",

"kind": "service",

"notes": "Primary endpoint is hosted Perpetua.sh API at https://www.perpetua.sh/api."

}

}

---

# Perpetua Skill (Hosted)

Overview

Use **Perpetua.sh hosted API** as the default path:

Load secrets with:

op run --env-file="$HOME/.openclaw/secrets.env" -- <command>

Credentials

Set API key via env var from any secret source (1Password, CI, `.env`, secret manager):

export PERPETUA_API_KEY="<your-key>"

Core endpoints (hosted)

# Connection status summary
curl -s "https://www.perpetua.sh/api/status" \
  -H "Authorization: Bearer $PERPETUA_API_KEY"

# Active connections
curl -s "https://www.perpetua.sh/api/connections" \
  -H "Authorization: Bearer $PERPETUA_API_KEY"

# Providers
curl -s "https://www.perpetua.sh/api/providers" \
  -H "Authorization: Bearer $PERPETUA_API_KEY"

Proxy call pattern

GET https://www.perpetua.sh/api/proxy/:provider/:path
Authorization: Bearer $PERPETUA_API_KEY

Optional: `?account=default` for explicit account selection.

Oura examples

> Avoid huge endpoints (`daily_activity`, detailed `sleep`) unless explicitly needed.

# Daily sleep
curl -s "https://www.perpetua.sh/api/proxy/oura/v2/usercollection/daily_sleep?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&account=default" \
  -H "Authorization: Bearer $PERPETUA_API_KEY" | jq .

# Daily readiness
curl -s "https://www.perpetua.sh/api/proxy/oura/v2/usercollection/daily_readiness?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&account=default" \
  -H "Authorization: Bearer $PERPETUA_API_KEY" | jq .

# Workout
curl -s "https://www.perpetua.sh/api/proxy/oura/v2/usercollection/workout?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&account=default" \
  -H "Authorization: Bearer $PERPETUA_API_KEY" | jq .

Google Calendar examples

# Upcoming primary calendar events
curl -s "https://www.perpetua.sh/api/proxy/gcal/calendars/primary/events?account=default&maxResults=10&orderBy=startTime&singleEvents=true&timeMin=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -H "Authorization: Bearer $PERPETUA_API_KEY" | jq '[.items[] | {summary, start}]'

# Calendar list
curl -s "https://www.perpetua.sh/api/proxy/gcal/users/me/calendarList?account=default" \
  -H "Authorization: Bearer $PERPETUA_API_KEY" | jq .

Connection management (hosted)

# Start OAuth flow for provider
curl -s -X POST "https://www.perpetua.sh/api/auth/connect/:provider/start" \
  -H "Authorization: Bearer $PERPETUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account":"default"}' | jq .authUrl

Troubleshooting

Local OSS note

Local `http://localhost:3001` is for OSS development only. Default operational path in this workspace is hosted Perpetua.sh.