API Reference

Quick start in 10 minutes.

Base URL: https://api.gregnote.com

Get API key →See examples

Quick start

Three calls to your first webhook.

01

Get your API key

Sign up at app.gregnote.com. Your live key starts with gk_live_.

02

Send your first bot

POST the meeting URL. The bot joins within 30 seconds.

terminal
curl -X POST https://api.gregnote.com/v1/bots \
  -H "Authorization: Bearer gk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '
    {
      "meeting_url": "https://meet.google.com/abc-def-ghi",
      "bot_name":    "Notetaker",
      "webhook_url": "https://yourdomain.com/webhooks/gregnote"
    }'
03

Receive the webhook

When the meeting ends, we POST to your webhook_url with the full transcript.

terminal
// Express.js example
app.post('/webhooks/gregnote', (req, res) => {
  const sig = req.headers['gregnote-signature'];
  // verify HMAC-SHA256 sig first
  const { event, transcript } = req.body;
  if (event === 'meeting.completed') {
    console.log(transcript.segments);
  }
  res.status(200).json({ ok: true });
});

Authentication

API keys

All requests must include your API key as a Bearer token in the Authorization header.

Live keys start with gk_live_. Test keys start with gk_test_. Keep your key secret. It cannot be recovered.

header
Authorization: Bearer gk_live_YOUR_KEY
# Error responses
401 "Invalid API key"
403 "Key revoked"

Endpoints

All endpoints.

POST/v1/bots

Send a bot to a meeting. Returns bot_id and status.

bots
GET/v1/bots/:id

Fetch current bot status: joining, waiting, joined, ended, failed.

bots
POST/v1/bots/:id/leave

Manually remove the bot from the meeting.

bots
GET/v1/meetings/:id/transcript

Fetch the diarised transcript once the meeting has ended.

meetings
GET/v1/meetings/:id/recording

Get a presigned URL to the raw audio recording (expires 1hr).

meetings
POST/v1/audio/transcriptions

Upload an audio file (up to 500 MB) and receive a transcript.

stt
POST/v1/transcriptions

Queue a large audio transcription job. Poll GET for status.

stt
GET/v1/transcriptions/:id

Poll transcription job status and retrieve result when complete.

stt
POST/v1/webhooks

Register a new webhook endpoint and receive its signing secret.

webhooks
GET/v1/webhooks

List all registered webhook endpoints.

webhooks

Webhooks

Event reference.

All webhook payloads are signed with HMAC-SHA256. Verify the Gregnote-Signature header before processing.

bot.joining

Bot has been dispatched to the meeting

bot.waiting

Bot is in lobby waiting for host admission

bot.joined

Bot is in the meeting and recording

bot.failed

Bot failed to join (meeting not found, kicked)

meeting.started

Audio capture has begun

meeting.ended

Meeting ended; transcript being generated

meeting.completed

Transcript ready, webhook includes full payload

transcription.queued

Async STT job has been enqueued

transcription.completed

Async STT job finished; transcript included

transcription.failed

STT job failed; error detail included

recording.ready

Presigned recording URL available

webhook verification (Node.js)
import { createHmac } from 'node:crypto';
function verifyWebhook(body, sig, secret) {
  const [t, v1] = sig.split(',');
  const timestamp  = t.replace('t=', '');
  const signature  = v1.replace('v1=', '');
  const expected   = createHmac('sha256', secret)
    .update(`${timestamp}.${body}`).digest('hex');
  return expected === signature;
}

Ready to build?

$200 credit on sign-up. API key in 30 seconds.

Get API key →