export const metadata = {
  title: { absolute: "FaithTranscripts API — Developer Documentation" },
  description:
    "Programmatic access to AI-powered transcript correction for faith content creators.",
  alternates: { canonical: "/docs/api" },
};

<div className="mb-2 font-medium text-gold text-xs uppercase tracking-widest">
  FaithTranscripts API
</div>

# Overview

The FaithTranscripts API gives your organization programmatic access to the
same deterministic + AI-validation pipeline that powers the dashboard. Submit
raw text, YouTube videos, or remote files and get back cleaned transcripts
with name, place, theology, church, and bible reference corrections applied.

## Base URL

```text
https://www.faithtranscripts.com/api/v1
```

## How it works

1. An organization member creates an API key from [Settings → API Keys](/settings/api-keys).
2. You call `POST /transcripts` with one of four source types: `paste`, `youtube`, `url`, or `upload`.
3. We run the deterministic replacement pass and, if requested, an AI validation pass.
4. You receive the corrected transcript — synchronously for small pastes, via polling, or via a webhook notification.

## Resources

Two primary resources; everything else hangs off these.

- **transcript** — the durable artifact (id, status, source, content, suggestions, ai pass status, timestamps).
- **job** — the unit of async work against a transcript (id, type, status, progress, error).

## First request

The smallest useful call creates a transcript from a pasted string of text.
This call runs the deterministic pass inline and responds with the corrected
transcript.

<EndpointBadge method="POST" path="/api/v1/transcripts" />

```bash
curl https://www.faithtranscripts.com/api/v1/transcripts \
  -H "Authorization: Bearer ft_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "paste",
    "title": "Sunday sermon",
    "content": "...transcript text..."
  }'
```

## Guiding principles

- **Reuse the internal contracts.** The public API is a thin, authenticated layer over the same pipeline the dashboard uses.
- **Org-scoped by default.** Every API key belongs to exactly one organization. All resources are owned by that org.
- **One resource model.** A transcript created via API has the same shape as one created in the dashboard.
- **Async-first, sync-friendly.** The pipeline is a job; sync is a convenience wrapper with a bounded timeout.

## Next steps

- [Authentication](/docs/api/authentication) — how keys work on the wire.
- [Quickstart](/docs/api/quickstart) — a complete first integration in five minutes.
- [Endpoint reference](/docs/api/reference) — every endpoint, every parameter.