Skyvern SDK: get started

Use an ordinary App, or an Agent when the workload needs agent identity. Alter builds provider requests from a reviewed contract and applies the same connection authorization, policy, approvals, and audit records as raw requests.

Install

npm install @alter-ai/sdk @alter-ai/skyvern
# Python (installs core automatically)
pip install alter-sdk-skyvern

The provider package includes only Skyvern types and response schemas and pins its contract version.

Connect and call

Store a Skyvern API key as a managed secret and retain its grant ID. Alter injects the key; it never belongs in operation input. This SDK reaches Skyvern Cloud only, because a self-hosted server has no fixed address to review.

import { App } from "@alter-ai/sdk";
import { SkyvernIntegration } from "@alter-ai/skyvern";
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
  const client = new SkyvernIntegration(app, { grantId: process.env.SKYVERN_GRANT_ID! });
  const result = await (await client.tasks.runTask({ body: { prompt: "Extract the pricing table", url: "https://example.com" } })).wait();
  console.log(result.bodyJson());
} finally {
  await app.close();
}

from alter_sdk import App
from alter_sdk_skyvern import SkyvernIntegration

async def first_call(api_key: str, grant_id: str):
    async with App(api_key=api_key) as app:
        client = SkyvernIntegration(app, {"grant_id": grant_id})
        call = await client.tasks.run_task(
            {"body": {"prompt": "Extract the pricing table", "url": "https://example.com"}}
        )
        result = await call.wait()
        return result.body_json()

Complete versioned contract

Contract 2026-10-31 contains every operation in Skyvern’s official OpenAPI document. The API reference links every operation to its complete input fields, response models, TypeScript and Python examples, and policy identity. Browse by resource under this provider’s API reference in the Integrations sidebar, or download the pinned OpenAPI specification. The Developer Portal provider view and alter integrations operations skyvern --version 2026-10-31 also expose the schemas.

Generated calls pin the Alter contract version. Skyvern’s own product, role, scope and subscription requirements still apply. There is no silent version fallback and no automatic write retry or pagination.

alter integrations execute skyvern skyvern.get_version_v1_version_get \
  --version 2026-10-31 --grant "$SKYVERN_GRANT_ID" --input '{}' --wait

Arguments use native path, query, headers, and body containers. Array query parameters are sent the way the provider’s document declares them: one delimited value where it declares explode: false (or a pipe- or space-delimited style), repeated keys otherwise. SDK methods preserve provider field names, decimal lexemes and large integers as strings when necessary. HTTP 204 returns null / None from the typed decoder. Binary responses use bodyBytes() / body_bytes(); the CLI can save them with --output-file.

Approvals

A policy rule can require approval for any operation. The call returns a pending approval; wait() resolves once the approver decides, and resume(approvalId) picks a pending approval up after a restart. Approval cards show the operation, its contract version and the request input the sensitivity review marked safe to display.

Uploads and approvals

files.uploadFile / files.upload_file and recipes.applyToJob / recipes.apply_to_job upload a file. Each binary input is a JSON object with filename, content_type, and content_base64, and a serialized input is limited to 5 MiB. Both files are treated as sensitive: under an approval, the file is held encrypted and the approver sees its name, type and size, never its contents.

A job application is published in its multipart form, with the résumé in resume_file, so a résumé need not sit at a URL Skyvern can fetch. A raw request may still send Skyvern’s JSON form with resume_url.

The audit exports are published as JSON pages. A raw request may still ask for format=csv.

Policy and sensitive data

Each operation keeps the policy identity the Skyvern catalog already published, its OpenAPI operationId (or a short id such as schedules_create), so a rule written for a raw request also governs the SDK method. The families are explained in Skyvern.

• Running a task, an agent, a script or a recipe, starting or extending a browser session, and a schedule that starts runs carry read, write, send, payment and delete. A run drives a real browser from a natural-language goal with the organization’s stored passwords and cards, so it can do any of these on any website. A rule on any one family covers it.
• Reading a browser session carries the same families, because the response holds its live remote-control address.
• admin covers credential storage, custom LLMs, the Twilio integration, SMS numbers and audit exports. payment is added where a stored card or a billed number is involved.
• Skyvern deletes agents and credentials with POST .../delete, so target the delete family rather than the method.

Payload capture follows the application’s capture setting, on managed and raw proxied calls alike: credentials are removed, every field Alter’s reviewed inventory for the provider marks sensitive is masked in requests and responses, including fields it locates only by operation, and binary bodies, calls that can return a credential and calls carrying raw card data are never stored. Metadata audit is unchanged. Under an approval, passwords, TOTP seeds, API keys, secret values, a browser address, request headers, a proxy location, inline workflow secrets, a YAML agent definition and uploaded files are held encrypted and shown masked. A request carrying raw card data cannot be held at all: createCredential with a card, or a stored card update, fails with sensitive_payment_input_requires_token under an approval rule.

Reading the organization’s API keys, a UI session token, the Azure and custom credential-service secrets, testing a stored password at a URL, and reading the current 2FA code or the received codes are refused by default with credential_minting_refused. They are not published as methods, and a raw request is refused. customLlms.updateCustomLlm / custom_llms.update_custom_llm is refused only when it keeps a stored secret and can move it to another host. An organization admin lifts a refusal with a credential_minting rule, outright or behind approval. Every row is listed in Skyvern.

Thirteen catalog rows are not published as methods: the routes above that Skyvern serves outside its published document, its legacy /api/v1 credential routes and its SMS configuration create. A raw request to one still classifies. A saved agent’s /v1/workflows spelling and the legacy /api/v1 spellings classify as the operation they serve.

Skyvern documents no 2xx failure: a run that fails is data in its status and failure_reason, so the call itself succeeds.

No call in this contract has run against real Skyvern; it comes from Skyvern’s published document.

Maintenance

The pinned official source, its hash, the generated methods and the policy mapping are checked together. Scheduled checks save upstream candidates and report additions, removals and schema changes; they never replace a published contract automatically. Existing contract versions remain available for installed SDKs and pending approvals.

Resume after a restart

Persist call.approvalId (TypeScript) or call.approval_id (Python), then construct a fresh provider client and call resume(savedId), followed by wait(). The stored approval selects the operation; this installed package verifies its provider and contract version before attaching the response validator. Mismatches raise ManagedOperationError, never silently decode using another contract. See persist-and-resume examples.

Rules for SDK functions

Policy operation fields also accept the published SDK function IDs listed by alter integrations operations skyvern. Use when.operation for a json_match or conditional require_approval rule, or match.operations for content_match (including redaction and step-up). Conditional approval can also use when.match.operations with parameter conditions. alter policy simulate --operation <function-id> tests that exact function.

Managed calls carry a server-verified function identity. Alter still evaluates policy against the actual method, URL and body after building the request from the authorized connection. Existing endpoint, method, host, catalog-operation and family rules continue to apply unchanged. A raw call can share an endpoint with several SDK functions and matches all of them; a function name never grants permission or bypasses existing restrictions.

For example, this rule requires approval for one function:

{
  "effect": "require_approval",
  "when": { "operation": "skyvern.run_task_v1_run_tasks_post" },
  "approval": { "approvers": ["reviewer@example.com"] }
}

Save it with alter policy rules create --app <app-id> --grant <grant-id> --type require_approval --body @rule.json, or select the function in the portal.