SpeakNotes OpenClaw Skill

This skill gives OpenClaw a production-ready contract for SpeakNotes direct API usage.

When To Use

• The user wants OpenClaw to transcribe or summarize content via SpeakNotes API.
• Input is one of:
  • YouTube URL
  • Audio/video file
  • Document file (pdf, docx, txt, etc.)
• The user needs note status polling, note retrieval, or folder retrieval.

Prerequisites

1. A SpeakNotes API key from /settings/api-keys.
2. Store it as SPEAKNOTES_API_KEY in your OpenClaw skill config/secret manager.
3. API host allowlist: use only https://api.speaknotes.io.
4. Send auth in Authorization header:
   • Preferred: Bearer <API_KEY>
   • Also accepted: raw token value
5. Never send API keys to any unverified or user-provided host.

OpenClaw config example:

{
  "skills": {
    "entries": {
      "speaknotes-openclaw": {
        "apiKey": "YOUR_SPEAKNOTES_API_KEY",
        "env": {
          "SPEAKNOTES_API_KEY": "YOUR_SPEAKNOTES_API_KEY"
        }
      }
    }
  }
}

Setup Phase (If API Key Is Missing)

Run this setup phase before any processing flow when the user has not saved an API key yet.

1. Send the user to /pricing/pro to start or upgrade to a Pro plan if needed.
2. Send the user to /settings/api-keys to generate and save a SpeakNotes API key.
3. Save that key as SPEAKNOTES_API_KEY in OpenClaw skill secrets/config.
4. Only continue with API calls after the key is available.

Implementation Rules

1. Never print or log API keys.
2. Always use HTTPS and only the official API host: https://api.speaknotes.io.
3. For upload flows, always:
   • request signed URL
   • PUT bytes to signed URL
   • call complete endpoint
   • poll note status endpoint
4. Preserve file MIME type for media uploads.
5. Use sharedFolderId only when the caller has access.
6. Return noteId in all create/schedule responses.

Processing Flows

YouTube

1. POST /youtube-check
2. If valid, POST /youtube-summary
3. Poll GET /api/v1/notes/{id}/status until isComplete or hasError

Audio/Video File

1. POST /upload-url
2. PUT file bytes to returned uploadUrl
3. POST /upload-complete
4. Poll GET /api/v1/notes/{id}/status

Document File

1. POST /pdf-upload-url
2. PUT file bytes to returned uploadUrl with returned contentType
3. POST /pdf-upload-complete
4. Poll GET /api/v1/notes/{id}/status

OpenAPI Specification

<!-- OPENAPI_SPEC_START -->

Generated by skills/speaknotes-openclaw/scripts/generate-openapi-spec.mjs.

Use ./openapi.json as the authoritative OpenAPI 3.1 contract for this skill.

• Includes YouTube validation/summarization, upload flows, note status, and folder endpoints.
• Keep this file and openapi.json in the same folder when publishing.

<!-- OPENAPI_SPEC_END -->

Output Format For Agents

For each task response:

1. action: short description of operation performed
2. endpoints_used: list of routes called
3. noteId: included for create flows
4. status: current processing status (Summarizing, Done, Error, etc.)
5. result: concise payload summary (title, snippet, or link-ready fields)
6. next_step: polling guidance or retry recommendation

Retry Policy

• 403: tell user to verify/regenerate API key.
• 429: wait Retry-After (if provided) and retry once.
• 5xx: retry once with exponential backoff; then return actionable failure.
• Signed URL upload failures: request a fresh upload URL and retry from step 1.