# ModelRunner Docs

- [ModelRunner API Documentation — One API for Every AI Model](https://modelrunner.ai/docs/index.md): Explore our guides and examples to start running AI models with ModelRunner
- [API keys](https://modelrunner.ai/docs/api-keys.md): Create, name, copy, and delete API keys from your ModelRunner profile
- [Request lifecycle](https://modelrunner.ai/docs/guides/request-lifecycle.md): How an inference request moves from submission to terminal state, and the platform guarantees around finalization.
- [FAQ](https://modelrunner.ai/docs/faq.md): Common questions about authentication, billing, supported file types, and platform limits.
- [Wrappers](https://modelrunner.ai/docs/guides/wrappers/overview.md): Turn a raw model into a purpose-built product — your own inputs and a baked-in prompt recipe — callable at a single endpoint.
- [Build a wrapper](https://modelrunner.ai/docs/guides/wrappers/authoring.md): Design, preview, and publish a wrapper end to end — guided by your AI assistant over the MCP server.
- [Prompt templates](https://modelrunner.ai/docs/guides/wrappers/prompt-templates.md): The Handlebars template that turns your wrapper's inputs into the prompt the base model receives — variables, lookup maps, helpers, and the rules to follow.
- [Switching base models](https://modelrunner.ai/docs/guides/wrappers/switching-base-models.md): Put one stable interface in front of several models — pick a default, let callers choose at request time, and bridge schema differences with per-model mappings.
- [Serverless GPUs](https://modelrunner.ai/docs/guides/serverless-gpus/overview.md): Run your own container workload on a ModelRunner GPU, called through the same queue API as the catalog — scale-to-zero, per-second billing, live workers and logs.
- [Quickstart](https://modelrunner.ai/docs/guides/serverless-gpus/quickstart.md): Create a deployment in the dashboard, submit your first job through the queue API, and read the result.
- [Queue API for deployments](https://modelrunner.ai/docs/guides/serverless-gpus/queue-api.md): Submitting jobs to your own deployment uses the same endpoint, reserved keys and envelope as a catalog model — with a handful of deliberate differences.
- [Cancel and terminal states](https://modelrunner.ai/docs/guides/serverless-gpus/cancellation.md): Deployment jobs are the one place on ModelRunner where cancel really cancels — and where CANCELLED is a state your poller must handle.
- [Billing](https://modelrunner.ai/docs/guides/serverless-gpus/billing.md): Deployments bill worker-seconds against your prepaid balance: a credit hold reserved up front, hourly settlement after the fact.
- [Environment variables and secrets](https://modelrunner.ai/docs/guides/serverless-gpus/environment-variables.md): How deployment env vars are stored, what the API will and will not return, and exactly how far their secrecy goes.
- [Lifecycle](https://modelrunner.ai/docs/guides/serverless-gpus/lifecycle.md): Pause, resume, update and delete a deployment — and what the workers panel and live logs tell you while it runs.
- [Quotas and capacity](https://modelrunner.ai/docs/guides/serverless-gpus/quotas.md): Per-account deployment and worker limits, the platform-wide capacity ceiling, and what to do when you hit either.
- [Language models (chat API)](https://modelrunner.ai/docs/guides/language-models.md): Run LLMs through an OpenAI-compatible chat completions endpoint — a base URL per model or one /v1 base for the whole catalog with GET /v1/models discovery (GitHub Copilot-ready), streaming, tool calling and JSON mode — plus the Anthropic-compatible endpoint Claude Code uses.
- [File uploads](https://modelrunner.ai/docs/guides/file-uploads.md): Upload images, audio, video, and other binary inputs to ModelRunner storage and pass the resulting URLs to model inputs.
- [Webhooks](https://modelrunner.ai/docs/guides/webhooks.md): Receive a signed POST when a request settles, instead of polling or holding a connection open.
- [Data retention](https://modelrunner.ai/docs/guides/data-retention.md): How long ModelRunner keeps your request payloads and generated media, how to shorten it, and how to delete a request's data outright.
- [MCP server](https://modelrunner.ai/docs/guides/mcp-server.md): Connect Claude Desktop, Claude Code, Cursor, and other MCP clients directly to ModelRunner — run models, manage files, and inspect requests from your AI assistant.
- [JavaScript Client](https://modelrunner.ai/docs/clients/js-client.md): Install, configure, and use the ModelRunner JavaScript/TypeScript SDK.
- [Python Client](https://modelrunner.ai/docs/clients/python-client.md): Install, configure, and use the ModelRunner Python SDK.
- [Next.js App Router](https://modelrunner.ai/docs/recipes-nextjs-app.md): Create a Next.js app (App Router) with a simple form that calls a ModelRunner model using the JavaScript client.
- [Authorization](https://modelrunner.ai/docs/api-reference/introduction.md): Use API keys in the Authorization header to access ModelRunner APIs.
- [Statuses & failure semantics](https://modelrunner.ai/docs/api-reference/request-semantics.md): How to tell a successful generation from a failed one on each surface.
- [Errors](https://modelrunner.ai/docs/api-reference/errors.md): Error response shape, status codes, and how to handle each class of failure.
- [Create Request](https://modelrunner.ai/docs/api-reference/create-request.md): Enqueue a new inference job for the specified endpoint. `{ownerName}/{modelName}` resolves to a model, a wrapper, or one of your own Serverless GPU deployments, in that order.
- [Get Request Status](https://modelrunner.ai/docs/api-reference/get-request-status.md): Check the current status of an inference request.
- [Get Request Result](https://modelrunner.ai/docs/api-reference/get-request-result.md): Retrieve the final output and metadata for a completed request.
- [Cancel Request](https://modelrunner.ai/docs/api-reference/cancel-request.md): Cancel a request.
- [List Requests](https://modelrunner.ai/docs/api-reference/list-requests.md): The authenticated account's requests, newest first. Filter by endpoint, deployment, status, or the `metadata` tags set at submit time (`metadata` is a URL-encoded JSON object of exact key/value matches, AND-combined). NOTE: read `billingStatus`, not `status`, to tell success from failure — a failed…
- [Get Request](https://modelrunner.ai/docs/api-reference/get-request.md): One request by id, owner-only. Same item shape (and the same `billingStatus` failure semantics) as the list.
- [Stream Request Updates (SSE)](https://modelrunner.ai/docs/api-reference/stream-request-updates-sse.md): Server-sent events for the authenticated account's requests: a `snapshot` event with the currently in-flight requests on connect, then an `update` event per status transition (terminal transitions included), with a heartbeat comment every 25s. This is an account-wide activity feed, not a per-request…
- [Set Request Visibility](https://modelrunner.ai/docs/api-reference/set-request-visibility.md): Owner-controlled publication state. Requests default to private; `public: true` lets non-owners see this request through catalog preview surfaces (model example pages). This is publication, not sharing — public requests are readable by anyone.
- [Delete Request Payloads](https://modelrunner.ai/docs/api-reference/delete-request-payloads.md): Deletes the request's stored input/output payloads and its output media from the CDN. Irreversible. The request row itself is kept (soft purge) with `payloadsPurgedAt` set. Only terminal, already-charged requests can be purged. See the Data Retention guide for retention headers and account defaults.
- [List Models](https://modelrunner.ai/docs/api-reference/list-models.md): Paginated public model catalog with free-text search and structured filters. Private models are unlisted here (direct reads by endpoint still resolve them — 'private' means unlisted, not access-controlled).
- [Get Catalog Facets](https://modelrunner.ai/docs/api-reference/get-catalog-facets.md): Counts of catalog models grouped by input→output modality pair and by capability, under the same filters as List Models. Only public models are counted, so the totals always agree with what List Models returns.
- [List Featured Models](https://modelrunner.ai/docs/api-reference/list-featured-models.md): The curated featured set, unpaginated. Same public projection as List Models — provider internals are never included.
- [Get Model Pricing](https://modelrunner.ai/docs/api-reference/get-model-pricing.md): Batch pricing read: a versioned, `pricingMode`-discriminated rate card per endpoint. Repeat the `endpoint` parameter for a batch (aliases may contain slashes, so endpoints are never comma-joined). Endpoints that resolve to no priceable model are reported under `notFound` instead of failing the batch…
- [Get Model OpenAPI Schema](https://modelrunner.ai/docs/api-reference/get-model-openapi-schema.md): The model's machine-readable OpenAPI document: its input schema (`components.schemas.Input`), output schema, and endpoint paths. What code generators and AI assistants should consume before calling a model. `alias` may itself contain slashes.
- [Search Catalog](https://modelrunner.ai/docs/api-reference/search-catalog.md): Unified free-text search across models and wrappers, with match provenance, comparable relevance scores, pricing context, and real example prompts. Recall-first: prefer 2-4 plain keywords over long natural-language phrases.
- [List Collections](https://modelrunner.ai/docs/api-reference/list-collections.md): Published model collections — curated groupings of related models. Private member models are withheld, and `modelCount` counts only the models actually returned.
- [Get Collection](https://modelrunner.ai/docs/api-reference/get-collection.md): One published collection with its member models. Unpublished collections are not readable here.
- [List GPUs](https://modelrunner.ai/docs/api-reference/list-gpus.md): The public GPU catalog. Pass `serverless=true` for the SKUs offered for [Serverless GPU deployments](/guides/serverless-gpus/overview) — without the filter the response can also include rows that only price catalog models and cannot be deployed. No API key required.
- [List Deployment Templates](https://modelrunner.ai/docs/api-reference/list-deployment-templates.md): The curated workload templates a Serverless GPU deployment can be created from, with their configuration fields. No API key required. Creating a deployment is done in the dashboard in this release.
- [Initiate Upload](https://modelrunner.ai/docs/api-reference/initiate-upload.md): Start a single-part upload. Returns a presigned `upload_url` to `PUT` the bytes to, and the canonical `file_url` to pass as a model input. The file row is created now, so an upload you never complete leaves a row whose `file_url` 404s. Walkthrough: [File uploads](/guides/file-uploads).
- [Initiate Multipart Upload](https://modelrunner.ai/docs/api-reference/initiate-multipart-upload.md): Start a multipart upload for a large file. `fileUrl` is the canonical public URL — keep it; it is the one to pass as a model input once the upload completes.
- [Get Multipart Part URL](https://modelrunner.ai/docs/api-reference/get-multipart-part-url.md): Presign one part of an in-flight multipart upload. Part numbers start at 1; every part except the last must be at least 5 MiB. Capture the `ETag` response header from each part `PUT` — Complete Multipart Upload needs it.
- [Complete Multipart Upload](https://modelrunner.ai/docs/api-reference/complete-multipart-upload.md): Assemble the uploaded parts into one object and record the file. This is where the multipart file row is created, so an object-lifecycle header belongs on this call rather than the initiate.
- [Upload File in Chunks](https://modelrunner.ai/docs/api-reference/upload-file-in-chunks.md): Send a file inline as small base64 chunks, assembled server-side. This exists for clients that can reach neither the S3 host nor the relay — prefer Initiate Upload everywhere else.
- [Relay Upload Bytes](https://modelrunner.ai/docs/api-reference/relay-upload-bytes.md): First-party fallback for the presigned `PUT`: send the raw bytes here and they are streamed to storage server-side. Call this only with the `relay_upload_url` returned by Initiate Upload with `relay: true` — the `upload_token` in that URL is the sole credential, is bound to one object key and conten…
- [List Files](https://modelrunner.ai/docs/api-reference/list-files.md): Your asset library, newest first — every file you uploaded plus every output a model produced for you. Always scoped to the authenticated account.
- [Get File Facets](https://modelrunner.ai/docs/api-reference/get-file-facets.md): How many of your files fall in each bucket, under the type, tag, and search filters you pass. Bucket filters (`sources`, `favoritesOnly`) are what is being counted, so they are ignored here.
- [Get File by URL](https://modelrunner.ai/docs/api-reference/get-file-by-url.md): Look a file up by its public URL when you hold the URL but not the id — for example to check whether an output you are displaying is one of yours, and whether you have favorited it.
- [Get File](https://modelrunner.ai/docs/api-reference/get-file.md): One file with every request it is linked to, as input or output.
- [Delete File](https://modelrunner.ai/docs/api-reference/delete-file.md): Removes the file from your library and drops its request links. The stored object is **not** deleted and its URL keeps resolving — and once the record is gone there is nothing left to find the object by, so set an expiry at [upload time](/guides/data-retention) for anything you want cleaned up autom…
- [Favorite File](https://modelrunner.ai/docs/api-reference/favorite-file.md): Marks the file as a favorite. Idempotent. A favorited file is also exempt from retention sweeps — see [data retention](/guides/data-retention).
- [Unfavorite File](https://modelrunner.ai/docs/api-reference/unfavorite-file.md): Removes the favorite. Idempotent — unfavoriting a file that was not favorited succeeds.
- [Assign Tag to File](https://modelrunner.ai/docs/api-reference/assign-tag-to-file.md): Tags one of your files. Pass `tagId` for an existing tag, or `name` to create-or-reuse one by case-insensitive name — exactly one of the two. Tagging also exempts a file from retention sweeps.
- [Remove Tag from File](https://modelrunner.ai/docs/api-reference/remove-tag-from-file.md): Unassigns a tag from a file. Idempotent, and leaves the tag itself in place.
- [List Tags](https://modelrunner.ai/docs/api-reference/list-tags.md): Your tags, each with the number of your files carrying it.
- [Create Tag](https://modelrunner.ai/docs/api-reference/create-tag.md): Creates a tag. Idempotent on the case-insensitive name — an existing tag with that name is returned unchanged.
- [Delete Tag](https://modelrunner.ai/docs/api-reference/delete-tag.md): Deletes the tag and unassigns it from every file. The files themselves are untouched.
- [Get Balance](https://modelrunner.ai/docs/api-reference/get-balance.md): The authenticated account's current credit balance, as an exact decimal string. An account that has never been credited reads as `"0"`.
- [Get Usage Summary](https://modelrunner.ai/docs/api-reference/get-usage-summary.md): Spend and request statistics for the authenticated account over a trailing window. `totalSpent` sums what was actually charged (exact decimal string), catalog inference and Serverless GPU worker time together — `serverlessSpent` breaks out the latter; `successRate` excludes failed generations (`bill…
- [Get Webhook Secret](https://modelrunner.ai/docs/api-reference/get-webhook-secret.md): The account's webhook signing secret (`{ "key": "whsec_…" }`), used to verify Standard-Webhooks signatures on deliveries. Created on first read.
- [Rotate Webhook Secret](https://modelrunner.ai/docs/api-reference/rotate-webhook-secret.md): Rotates the signing secret and returns the new value. Deliveries signed with the old secret stop verifying immediately.
- [List Webhook Deliveries](https://modelrunner.ai/docs/api-reference/list-webhook-deliveries.md): The account's webhook delivery log, newest first.
- [Replay Webhook Delivery](https://modelrunner.ai/docs/api-reference/replay-webhook-delivery.md): Re-queues one delivery for another attempt with a fresh signature. Owner-only.

## OpenAPI Specs

- [openapi](/docs/openapi.json)
- [platform-openapi](/docs/platform-openapi.json)