---
name: speaknotes
description: Use when an AI agent needs to call the SpeakNotes API directly to transcribe audio or video, summarize text or YouTube videos, or read and write a user's SpeakNotes notes and folders.
---

# SpeakNotes Skill (skills.sh)

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

## When To Use

- The user wants a transcript or a structured summary from SpeakNotes.
- Input is one of:
  - Audio or video file
  - A public audio URL
  - A YouTube URL
  - Text or an existing transcript
- The user wants to read, create, update, or delete their SpeakNotes notes and folders.
- The user wants to know what their SpeakNotes API usage is costing.

## Prerequisites

1. A SpeakNotes API key from `/settings/api-keys`. Any signed-in account can create one.
2. Store it as `SPEAKNOTES_API_KEY` in your agent runtime.
3. API host allowlist: use only `https://api.speaknotes.io`.
4. Send auth as `Authorization: Bearer <API_KEY>`.
5. Never send API keys to unverified or user-provided hosts.

## Setup Phase (If API Key Is Missing)

1. Send the user to `/settings/api-keys` to create a key. No paid plan is required.
2. Suggest a sandbox key (`sn_test_`) while building, and a live key (`sn_live_`) for real work.
3. Save that key as `SPEAKNOTES_API_KEY` in the agent environment.
4. Only continue with API calls after the key is available.

## Sandbox Mode

Keys beginning `sn_test_` run every route against fixed output. No model runs, no credits are
charged, and writes land in a separate sandbox library. The response shape is identical to live,
so build against sandbox first and switch the key when the output looks right.

## Credits

- One credit is one started minute of transcribed media.
- Summarizing text costs 2 credits. Asking a question about a note costs 1. Reads are free.
- Free accounts get 60 credits a month, Pro accounts 2,000. Extra credits are prepaid.
- Check `GET /v1/usage` before starting a long job. Every charging response returns
  `creditsCharged` and an `X-Credits-Remaining` header.
- Running out returns `402` with code `insufficient_credits`. Do not retry it: tell the user.

## 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 the upload URL
   - `PUT` bytes to the signed URL
   - call the complete endpoint
   - poll the note status endpoint
4. Preserve the file MIME type for media uploads.
5. Return `noteId` in all create responses.
6. Read `GET /v1` first when unsure: it needs no credential and lists every resource, scope,
   rate limit, and credit cost.

## Processing Flows

### Audio or video file

1. `POST /v1/uploads` with `fileName` and `contentType`
2. `PUT` file bytes to the returned `uploadUrl`
3. `POST /v1/uploads/{noteId}/complete` (credits are charged here)
4. Poll `GET /v1/notes/{noteId}/status` until `isComplete` or `hasError`
5. Read the result with `GET /v1/notes/{noteId}`

### Public audio URL

1. `POST /v1/transcriptions` with `audioUrl`. The transcript comes back inline.

### YouTube

1. `POST /v1/youtube-summaries` with `youtubeUrl`. The summary comes back inline.

### Text or an existing transcript

1. `POST /v1/summaries` with `text` and an optional `styleId`.

### Reading and writing the library

- `GET /v1/notes`, `GET /v1/notes/{id}`, `GET /v1/notes/{id}/transcript`
- `POST /v1/notes`, `PATCH /v1/notes/{id}`, `DELETE /v1/notes/{id}`
- `GET /v1/folders`, `POST /v1/folders`, `PATCH /v1/folders/{id}`, `DELETE /v1/folders/{id}`
- `POST /v1/notes/{id}/questions` to answer a question from a note's transcript

## Styles

`note` (default), `transcript`, `bulletpoints`, `meeting-notes`.

## OpenAPI Specification

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

- Every operation has an `operationId`, a description, typed parameters, response schemas, and
  the scopes it needs.
- `x-speaknotes-credits` on each operation says what it costs.
- Keep this file and `openapi.json` in the same folder when publishing.

## Scopes

Keys and OAuth tokens carry scopes: `notes:read`, `notes:write`, `folders:read`, `folders:write`,
`transcriptions:write`, `summaries:write`, `usage:read`. A `403` with code `insufficient_scope`
names the scope that is missing; the user must create a key that includes it.

## MCP Alternative

If the runtime speaks MCP, connect to `https://api.speaknotes.io/mcp` over Streamable HTTP
instead of calling REST directly. `initialize` and `tools/list` work without a credential.

## 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`)
5. `result`: concise payload summary (title, snippet, or link-ready fields)
6. `credits`: `creditsCharged` and remaining balance, when the call spent any
7. `next_step`: polling guidance or retry recommendation

## Error Handling

Every failure returns `{"error": {"type", "code", "message", "doc_url"}}`. Branch on `code`.

- `invalid_token` (401): tell the user to check or regenerate the key.
- `insufficient_scope` (403): name the missing scope from the message.
- `insufficient_credits` (402): tell the user to top up at `/developers/pricing`. Do not retry.
- `rate_limited` (429): wait `Retry-After`, then retry once.
- `content_policy` (422): do not retry the same content.
- `upstream_failure` (502): retry once with backoff, then return an actionable failure.
- Signed URL upload failures: request a fresh upload URL and retry from step 1.

Full list: https://speaknotes.io/developers/errors

## Variant Notes

- Use `speaknotes-openclaw` when you specifically need OpenClaw metadata/config hints.
- Use this `speaknotes` skill for platform-agnostic skill registries such as skills.sh.