# Skribby REST API

API-first platform for capturing, transcribing, and processing online meetings. 
Deploy meeting bots into Zoom, Microsoft Teams, and Google Meet to receive real-time 
or post-call transcription, audio, and structured data.

## Quick Start

1. **[Sign up](https://platform.skribby.io)** for a free account
2. **[Generate API key](https://platform.skribby.io/?to=api-keys)** from your dashboard
3. **Create your first bot:**

```bash
curl -X POST 'https://platform.skribby.io/api/v1/bot' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transcription_model": "whisper",
    "meeting_url": "https://meet.google.com/abc-def-ghi",
    "service": "gmeet",
    "bot_name": "My First Bot"
  }'
```

## Webhooks

Skribby can send real-time updates to your server via webhooks. When you provide a `webhook_url` parameter, Skribby will POST events to that URL as they occur.

<h3>Webhook Format</h3>

All webhook payloads follow a consistent format:

```json
{
  "type": "{event}",
  "data": {...}
}
```

<h3>Available Events</h3>

<h4>`status_update`</h4>

Sent when a bot's status changes. The `data` object contains:

- `old_status` (string): The previous status of the bot
- `new_status` (string): The new status of the bot

**Example:**

```json
{
  "type": "status_update",
  "data": {
    "old_status": "joining",
    "new_status": "recording"
  }
}
```


Version: v1

## Servers

Production server
```
https://platform.skribby.io/api/v1
```

## Security

### bearerAuth

API key authentication. Get your API key from the [Skribby dashboard](https://platform.skribby.io?to=api-keys).
Include it in the Authorization header: `Authorization: Bearer YOUR_API_KEY`


Type: http
Scheme: bearer

## Download OpenAPI description

[Skribby REST API](https://docs.skribby.io/_bundle/rest-api/openapi.yaml)

## Bot Operations

Create and manage meeting bots

### Create Bot

 - [POST /bot](https://docs.skribby.io/rest-api/openapi/bot-operations/createbot.md): Create a new meeting bot to join and record a meeting.

### Validate Bot Configuration

 - [POST /bot/validate](https://docs.skribby.io/rest-api/openapi/bot-operations/validatebot.md): Validate a meeting bot configuration without actually creating or starting the bot.
This endpoint accepts the same parameters as the Create Bot endpoint and performs
all validation checks including meeting URL format, authenticated account validity,
and configuration parameters.

Use this endpoint to verify your bot configuration before deploying, or to validate
user input in your application before scheduling a bot.

### Get Bot

 - [GET /bot/{id}](https://docs.skribby.io/rest-api/openapi/bot-operations/getbot.md): Retrieve information about a specific bot, including its current status,
transcript (if available), participants, and lifecycle events.

### Update Bot

 - [PATCH /bot/{id}](https://docs.skribby.io/rest-api/openapi/bot-operations/updatebot.md): Update a scheduled meeting bot. All parameters are optional, provide only the fields you want to change; unspecified fields will remain unchanged.

### Delete Bot Data

 - [DELETE /bot/{id}](https://docs.skribby.io/rest-api/openapi/bot-operations/deletebot.md): Delete all data related to the bot, including transcription and recording.  
Bots can only be deleted if they are scheduled or not in an active state (booting, joining, recording, processing or transcribing).  
Be aware, this action is not reversible!

### Send Chat Message

 - [POST /bot/{id}/chat-message](https://docs.skribby.io/rest-api/openapi/bot-operations/sendchatmessage.md): Send a chat message as the meeting bot

### Stop Bot

 - [POST /bot/{id}/stop](https://docs.skribby.io/rest-api/openapi/bot-operations/stopbot.md): Stop a running meeting bot. This will cause the bot to leave the meeting
and begin processing the recording.

### Get Scheduled Bots

 - [GET /bot/scheduled](https://docs.skribby.io/rest-api/openapi/bot-operations/getscheduledbots.md): Retrieve all scheduled bots that haven't started yet. Returns an array 
of bot objects with status "scheduled".

## Recording Operations

Upload and transcribe recordings

### Create Recording

 - [POST /recording](https://docs.skribby.io/rest-api/openapi/recording-operations/createrecording.md): Upload and transcribe a recording file or re-transcribe an existing meeting bot recording.

You have three options:
1. Upload a file directly - Provide recording_file and transcription_model
2. Provide a URL - Provide recording_url and transcription_model
3. Re-transcribe from meeting bot - Provide meeting_bot_id (optionally override transcription parameters)

When using meeting_bot_id, the recording and default transcription settings will be copied from the specified meeting bot.
You can override transcription_model, lang, profanity_filter, and custom_vocabulary parameters if needed.

### Get Recording

 - [GET /recording/{id}](https://docs.skribby.io/rest-api/openapi/recording-operations/getrecording.md): Retrieve information about a specific recording, including its transcription
status and transcript (if available).

### Delete Recording Data

 - [DELETE /recording/{id}](https://docs.skribby.io/rest-api/openapi/recording-operations/deleterecording.md): Delete all data related to the recording, including transcription and recording.  
Be aware, this action is not reversible!