Skip to main content
Skyvern’s REST API is versioned in the URL path. The current and only supported version is v1, served from https://api.skyvern.com/v1/.

​
How versioning works

The major version appears once, as the first path segment. It never appears in a header, query parameter, or Accept media type. Skyvern does not use date-based or header-negotiated versions. If your client pins https://api.skyvern.com/v1, no deployment we make will change the shape of a response you already depend on.

​
What counts as backward compatible

Treat the following as expected within v1, and make sure your client tolerates them:
  • New endpoints and new HTTP methods on existing paths
  • New optional request parameters and request body fields
  • New fields in response bodies
  • New values in existing enums (for example, a new run status or failure reason)
  • New or reworded human-readable detail strings on error responses
  • Changes to the ordering of JSON object keys or of items in an unordered collection
The practical rule: ignore unknown fields rather than failing on them, and treat an unrecognized enum value as “something newer than my client” instead of an error.

​
What we will not do inside v1

These are breaking changes. They only ship in a new major version, never into v1:
  • Removing or renaming an endpoint, a request field, or a response field
  • Changing the type or format of an existing field
  • Making an optional parameter required, or adding a new required parameter
  • Removing a value from an enum
  • Changing the HTTP status code or error code for an existing failure mode
  • Changing the authentication a route requires

​
Stability guarantees by surface

​
Deprecation and sunset policy

When we do deprecate part of the API, this is what you can count on:
  • At least 6 months notice. That is the minimum time between the deprecation announcement and the sunset date on which the endpoint stops serving traffic. Removing an entire major version gets at least 12 months.
  • A changelog announcement on the Skyvern changelog, naming the affected endpoints, the replacement, and the sunset date.
  • Machine-readable response headers on every response from a deprecated endpoint, following RFC 9745 (Deprecation) and RFC 8594 (Sunset).
  • deprecated: true in the OpenAPI specification for the affected operation, parameter, or schema field, so generated clients and API tooling surface the warning automatically.
  • No silent removals. An endpoint that has not been announced, header-flagged, and given its full notice window will not be turned off.
A response from a deprecated endpoint looks like this:
Deprecation carries the moment the endpoint became deprecated, Sunset the moment it stops responding, and the Link header points at the announcement explaining the migration.
No /v1 endpoint is deprecated today, so these headers are not present on any current response. The two deprecations in flight are field-level and documented in place: the title query parameter on GET /v1/agents (use search_key) and publish_workflow on task creation.

​
Building a client that survives changes

  • Pin the version prefix (/v1/), not a specific SDK patch release.
  • Parse responses leniently: ignore unknown fields, default unknown enum values to a safe branch.
  • Log any response carrying a Deprecation or Sunset header, and alert on it — that header is the earliest programmatic signal you will get.
  • Watch the changelog for announcements, and diff the OpenAPI specification in CI if you generate your own client.

​
Where changes are announced

Questions about a migration: support@skyvern.com.