# Shorty API — REST for summaries, transcription & subtitles

> The Shorty developer API turns YouTube videos, web pages, and media into summaries, transcriptions, and subtitles over a versioned REST surface — the same engine behind the Shorty app, with API keys, idempotency, rate limits, webhooks, and a TypeScript SDK.

## What it does

Shorty summarizes YouTube videos, web pages, and pasted text; transcribes audio and video; and generates subtitles. The API exposes those capabilities as async jobs you start with one call and poll (or receive a webhook) when they finish. Every resource is scoped to the authenticated account.

## Base URL

All endpoints live under one versioned base. Paths in this documentation are relative to it:

```text
https://aishorty.com/v1
```

## Authentication

Send a `shk_live_` API key (create one in Settings → API keys) or an OAuth 2.1 access token as a Bearer token on every request. Keys are shown once at creation — store them server-side; never ship a key to a browser.

```http
Authorization: Bearer shk_live_your_key
```

## Quickstart

Reach your first `200` in under five minutes:

1. Create an API key in Settings → API keys and copy it (shown once).
2. Confirm the key works by reading your usage.
3. Start a summary job — it returns `202` with a `job_id`.
4. Poll the job until it finishes (or subscribe to a webhook).

**1. Check your usage (verifies the key)**

curl:

```bash
curl https://aishorty.com/v1/usage \
  -H "Authorization: Bearer shk_live_your_key"
```

TypeScript (@aishorty/sdk):

```typescript
import { Shorty } from '@aishorty/sdk'

const shorty = new Shorty({ apiKey: process.env.SHORTY_API_KEY })
const usage = await shorty.usage.get()
console.log(usage.plan, usage.limits)
```

**2. Start a summary job**

curl:

```bash
curl -X POST https://aishorty.com/v1/summaries \
  -H "Authorization: Bearer shk_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "source": "youtube",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }'
```

TypeScript (@aishorty/sdk):

```typescript
const job = await shorty.summaries.create({
    source: 'youtube',
    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
})
```

**3. Poll the job until it is done**

curl:

```bash
curl https://aishorty.com/v1/jobs/JOB_ID \
  -H "Authorization: Bearer shk_live_your_key"
```

TypeScript (@aishorty/sdk):

```typescript
const done = await shorty.jobs.waitFor(job.job_id)
console.log(done.status, done.output)
```

## Conventions

- **Async jobs.** Write endpoints return `202 Accepted` with a `job_id` and a `tracking_url`; poll `GET /v1/jobs/{id}` or receive a webhook.
- **Idempotency.** Send an `Idempotency-Key` header on POSTs; a retry with the same key and body replays the original response for 24 hours.
- **Rate limits.** 60 requests/minute on the free tier, 300/minute on paid. The bucket is per API key when you authenticate with a `shk_live_` key, and per user when you call as an OAuth/MCP client. Responses carry IETF `RateLimit` headers.
- **Pagination.** List endpoints return `{ data, has_more, next_cursor }`; pass `next_cursor` back as `?cursor=`.
- **Errors.** Every error is an RFC 9457 `application/problem+json` body with a stable `code` you can switch on.

## Explore

- [API reference](/docs/api-reference) — The generated OpenAPI reference — one interactive page per operation.
- [Operations](/docs/api/operations) — One page per endpoint, with examples.
- [OpenAPI spec](/api/openapi) — The machine-readable OpenAPI 3.1 document.
- [TypeScript SDK](https://github.com/DevinoSolutions/shorty-sdk) — @aishorty/sdk — the official Node client.
- [Webhooks](/docs/api/webhooks) — Receive events instead of polling.
- [Errors](/docs/api/errors) — Every error code and how to fix it.
- [Changelog](/changelog) — Dated API changes and additions.
- [For AI agents](/docs/ai) — MCP, llms.txt, and Markdown twins for agents.
- [Developers overview](/developers) — The platform at a glance — REST, SDK, and MCP.
- [Product guides](/docs) — Using Shorty itself — summarizers, transcription, converter, apps.