Developer API

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:

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.

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:

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

TypeScript (@aishorty/sdk):

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:

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):

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:

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

TypeScript (@aishorty/sdk):

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 — Interactive reference for every endpoint (Scalar).
• Operations — One page per endpoint, with examples.
• OpenAPI spec — The machine-readable OpenAPI 3.1 document.
• TypeScript SDK — @aishorty/sdk — the official Node client.
• Webhooks — Receive events instead of polling.
• Errors — Every error code and how to fix it.
• Changelog — Dated API changes and additions.
• For AI agents — MCP, llms.txt, and Markdown twins for agents.
• Developers overview — The platform at a glance — REST, SDK, and MCP.
• Product guides — Using Shorty itself — summarizers, transcription, converter, apps.