AI agent skill - Recnote API

If your team builds with an AI coding agent (Claude Code, Cursor, or any agent that loads a SKILL.md / rules file), you can hand it this skill so it knows the Recnote API end to end — endpoints, auth, payloads, debugging — and can scaffold a client or test calls without you re-explaining the API each time.

Install

Save the block below as .claude/skills/recnote-api/SKILL.md in your project (or paste it into your agent’s rules / context file). Then ask your agent things like “send consultation.wav to Recnote and show me the note” or “scaffold a Python client for the chunked flow”.

---
name: recnote-api
description: "Integrate or test the Recnote API (transcription + AI clinical-note generation). Use when calling /api/v1, scaffolding a client, sending audio for a note, streaming chunks, or debugging a 401/502."
---

# Recnote API

Base URL: https://api.recnote.ai
Auth: `Authorization: Bearer rec_sk_...`  (or header `X-API-Key: rec_sk_...`)
Set the key as env RECNOTE_API_KEY before running examples.

## Endpoints
- GET  /api/v1/ping                         verify key
- POST /api/v1/transcriptions               audio -> { transcript }
- POST /api/v1/notes                         audio OR transcript -> { transcript, note }
- POST /api/v1/sessions                      open chunked session -> { sessionId }
- POST /api/v1/sessions/:id/chunks           push one audio chunk
- POST /api/v1/sessions/:id/notes            generate from accumulated chunks

Metadata for note endpoints (multipart fields or JSON keys):
language (sv/en/fi/nb/da/de/tr/ar), templateSections (JSON string),
template (id), sideNote, primaryProfession, customTemplate.

## One-shot note from audio
curl -X POST "$RECNOTE_BASE/api/v1/notes" \
  -H "Authorization: Bearer $RECNOTE_API_KEY" \
  -F "file=@consultation.wav" -F "language=sv"

## Note from transcript (JSON)
curl -X POST "$RECNOTE_BASE/api/v1/notes" \
  -H "Authorization: Bearer $RECNOTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transcript":"...","language":"sv"}'

## Custom template
Add field: templateSections='[{"sectionName":"Anamnes","aiRules":{"autoFill":true}}]'
Returned note.sections mirrors it; note.combined is full text.

## Chunked streaming
SID=$(curl -s -X POST "$RECNOTE_BASE/api/v1/sessions" -H "Authorization: Bearer $RECNOTE_API_KEY" | jq -r .sessionId)
curl -X POST "$RECNOTE_BASE/api/v1/sessions/$SID/chunks" -H "Authorization: Bearer $RECNOTE_API_KEY" -F "file=@chunk.webm" -F "language=sv"
curl -X POST "$RECNOTE_BASE/api/v1/sessions/$SID/notes" -H "Authorization: Bearer $RECNOTE_API_KEY" -H "Content-Type: application/json" -d '{"language":"sv"}'

## Response
{ "transcript": "...", "note": { cause, subjective, objective, assessment,
  plan, diagnoses[], coding_codes[], sections[], combined, tasks } }
note.combined drops straight into an EHR text field.

## Errors
401 invalid key · 400 no file/transcript · 413 audio >500MB · 502 upstream failed

What the agent can then do

Generate a typed client (Node, Python, C#, …) for either flow.
Wire the chunked session loop to your recorder.
Map the note JSON onto your EHR fields.
Reproduce and explain failed calls (401, 502, …) against your key.

The skill contains no secrets — set your RECNOTE_API_KEY in the environment your agent runs in, never inside the skill file.