API & MCP

Authentication

One key, one header, and every endpoint under a single base URL.

In short

Create an API key in Settings → API keys and send it as a bearer token: Authorization: Bearer pk_live_…. Every endpoint lives under https://pepys.co/api/v1. Usage draws from your account credit balance at 1 credit = 1 minute, so an unattended integration should have auto-reload enabled.

Create an API key

Open Settings → API keys and create a key. The full key is shown once, at creation, and starts with pk_live_. Copy it into your secret store at that moment – Pepys will not display it again.

Each key belongs to a single Pepys account, and every request made with it is billed to that account's credit balance.

Send it as a bearer token

Pass the key in the Authorization header of every request. All endpoints are relative to https://pepys.co/api/v1.

curl

curl https://pepys.co/api/v1/transcriptions \
  -H "Authorization: Bearer pk_live_your_key"

What usage draws on

Transcription is metered in credits: 1 credit = 1 minute, and credits never expire. Each accepted job debits the account's balance, so the same balance you top up in the app covers the API.

For unattended jobs, turn on auto-reload so a long-running integration does not pause at a zero balance. A request made with an empty balance fails with 402 – see errors and limits.

Connecting an AI agent instead

If the caller is an MCP client rather than your own code, you do not need a key at all: the hosted MCP connector authenticates with OAuth. A key is only needed for the local pepys-mcp server or direct REST calls.

Authentication – questions, answered

Where do I create a Pepys API key?

In Settings → API keys. The key starts with pk_live_ and is displayed once at creation, so store it when you copy it.

What is the API base URL?

https://pepys.co/api/v1. Every documented endpoint is relative to it, including transcriptions, uploads, podcasts, and webhooks.

How is API usage billed?

Against the same credit balance as the app: 1 credit = 1 minute, credits never expire. Enable auto-reload so jobs that run unattended do not pause at a zero balance.

Do I need an API key to connect ChatGPT or Claude?

No. The hosted MCP connector uses OAuth sign-in. An API key is only needed for direct REST calls or the local pepys-mcp server.

Try it on your own audio

Create a free account and transcribe a recording – 60 minutes are included, no card required. Still stuck? Email contact@pepys.co or see the support page.