> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Build with your agent

> Have the coding agent that already uses Importly's MCP server add downloads, transcripts, or metadata to your app with the same API key.

If Importly is connected to Claude Code or Cursor, the agent can also write the integration into your codebase. Your app uses the same API key and the same prices as the MCP server, through the REST API at `https://api.importly.io`.

## Ask for it

Tell the agent what the feature should do. These prompts work as written:

Import from URL

Add an "import from URL" option to our upload form using Importly. Download the media server-side, then save the file the same way we save normal uploads.

Transcripts for every video

When a user adds a video link, use Importly to fetch its transcript and store the text and timestamped segments with the video.

Link previews

Show a preview card (title, duration, thumbnail) when someone pastes a video URL. Use Importly basic metadata.

The agent calls `get_integration_guide` with your stack (`node`, `nextjs`, `python`, or `curl`) and the use case. The guide costs nothing and returns code for each part of the integration.

## What a good integration includes

Check the agent's work against this list:

**1. The key stays on the server**

`IMPORTLY_API_KEY` is read from an environment variable in server code only. It's never in client bundles or committed to the repo.

**2. Jobs are started from your backend**

A server route calls `POST /import`, `/transcribe`, or `/metadata` and stores the `jobId` with your record.

**3. Results arrive by webhook**

A webhook route receives the result and updates the record. Fields sit directly on `data` (`data.mediaUrl`, `data.text`), not under `result`. See [Webhooks](/docs/webhooks.md).

**4. Polling covers failures**

Failed jobs don't send webhooks, so a fallback polls `GET /<type>/status?id=` every few seconds and records `failed` jobs with their `message`.

**5. Errors are handled**

`402` means the balance is too low, and `429` means back off and retry. See [Errors & rate limits](/docs/error-handling.md).

> [!WARNING]
>
> `mediaUrl` links expire after 7 days. If your app keeps files, copy them to your own storage when the webhook arrives, or set `store: true` to [deliver them to your bucket](/docs/s3-storage.md).

## Without an agent

Follow the [quick start](/docs/quick-start.md), or use the API reference. Every page has a **Copy page** menu that gives you the Markdown version to paste into any AI tool.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.