@driftstack/api-types

Zod schemas + TypeScript types for the public Driftstack API. The single source of truth for the API contract — the OpenAPI 3.1 spec is generated from these schemas, the official TypeScript SDK (@driftstack/sdk) re-exports the inferred types, and other-language SDKs (Python, Go) generate types from the OpenAPI spec.

Status: pre-1.0. While the package is 0.x, a minor version can change the surface and a patch never does; all supported schemas and compatibility rules are documented below.

Install

npm install @driftstack/api-types

You usually don't need to install this directly — @driftstack/sdk carries the same types. Install it explicitly only if you want to:

• Use the Zod schemas to validate API responses you receive through your own HTTP client.
• Generate code (other languages, custom clients) from the inferred types.
• Build server-side adapters or middleware that conform to the same contract.

Usage

import { CreateSessionRequestSchema, type Session, type Problem } from '@driftstack/api-types';

// Validate an inbound request body before passing it to your handler.
const parsed = CreateSessionRequestSchema.parse(req.body);

// Use the inferred type as a function parameter.
function handle(session: Session) {
  console.log(session.id, session.status);
}

What's exported

The schemas of the public API: what a program sends to and receives from Driftstack. Sign-in, API keys, team membership, billing and crypto orders are managed in the Driftstack dashboard and are not part of this package.

• Sessions: Session, SessionState, CreateSessionRequest, NavigateRequest, InteractRequest, WaitRequest, CaptureRequest, ExtractRequest, plus their *Response counterparts.
• Agent sessions: AgentSession, the create and message requests and responses, the step and intent types a turn reports, and the session-secret shapes (CreateAgentSessionSecretRequest, AgentSessionSecret, ListAgentSessionSecretsResponse).
• Profiles and snapshots: Profile, CreateProfileRequest / UpdateProfileRequest, clone, import and export shapes, ProfileSnapshot.
• Saved proxies and egress: the proxy shapes and the OpenVPN and WireGuard configurations.
• Device profiles, recipes, webhooks, usage, rate limits and status: ARCHETYPE_REGISTRY, recipe shapes, WebhookEndpoint, WebhookDelivery, UsagePeriodSummary, UsageSeriesResponse, GetAccountRateLimitsResponse, the status incident shapes.
• Discriminated unions: InteractAction, WaitCondition.
• Common shapes: Problem (RFC 7807 error envelope), PaginationQuery, prefixed-id branded types (AccountId, SessionId, ProfileId, WebhookEndpointId, WebhookDeliveryId).
• Closed enums: AccountTier, SessionStatus, WebhookEventType, WebhookDeliveryStatus.
• Stable problem-type URIs: PROBLEM_TYPES.
• OpenVPN config helpers: DANGEROUS_OPENVPN_DIRECTIVES, findUnsupportedOpenvpnLines, stripUnsupportedOpenvpnLines — the directive list the API refuses inside an OpenVPN config_blob (script-executing directives, script-security 2+) plus the line-level finder / stripper, so a client can name the line the API will refuse before sending it.
• *Input variants (per the z.input / z.output distinction) for shapes with server-side defaults — see the SDK README for the full pattern.

Versioning

0.x.y follows SemVer's pre-1.0 rules: breaking changes use a minor version and compatible fixes use a patch version.

Install normally. npm install @driftstack/api-types writes a caret range, and for a 0.x package npm resolves a caret to PATCH releases only — which is what you want, because a minor version can change the surface and a patch never does. Read the changelog before moving to a new minor. Pin an exact version only if you need a byte-for-byte reproducible build, and note that your lockfile already gives you one.

Changelog

0.4.0 — 2026-10-04

Nothing was removed and nothing was narrowed; every addition is optional or new.

• Added: session secrets. CreateAgentSessionSecretRequestSchema, AgentSessionSecretSchema, ListAgentSessionSecretsResponseSchema and AgentSessionSecretHandleSchema, with their types, and the limits they are built from (AGENT_SESSION_SECRET_DEFAULT_TTL_SECONDS, _MIN_TTL_SECONDS, _MAX_TTL_SECONDS, _MAX_PER_SESSION, _LABEL_MAX_CHARS, _MAX_UTF8_BYTES): the body and answers of /v1/agent-sessions/{id}/secrets.
• Added: FrameMatchSchema and FrameMatch, and an optional frame_match on CaptureRequest: a dom_snapshot reads one embedded frame named by its address (host, path_prefix, query). Strict: an unknown key is refused.
• Added: Session.proxy_id (optional, nullable; on CreateSessionResponse too): the saved proxy the session's traffic goes out through. A missing key means "not reported", never "no proxy".
• Added to AgentIntent: an optional frame on a wait (selector_visible, on a session whose device can act inside a frame), and an optional attribute on an extract with a selector, with AGENT_EXTRACT_ATTRIBUTE_MAX_CHARS and AGENT_EXTRACT_ATTRIBUTE_PATTERN. The same two fields are accepted in a recipe's intent_log. An interact frame is documented for a tap as well as a type, and a type with an empty value is documented as clearing the field.
• Changed: ARCHETYPE_REGISTRY. The held iphone17_ios18_7_chrome148 and iphone17_ios18_7_chrome149 entries are based on Safari 26.6 (safariVersion: '26.6', baseArchetype: 'iphone17_ios18_7_safari26_6'; they were 26.4) and stay status: 'planned'. The same 106 entries, in a different order.

0.3.0 — 2026-10-03

Breaking. The package now carries the public API only. The account, API-key and scope, sign-in, device sign-in, billing and crypto-order schemas, the staff-tool schemas and the desktop app's input-channel types are no longer exported: those are managed in the Driftstack dashboard or used only by Driftstack's own apps. 0.2.0 is deprecated.

• SessionPurposeSchema has one value, production_customer, the default. Session.purpose and CreateSessionRequest.purpose are typed the same way.
• The incident schemas are the public status page's: Incident, IncidentUpdate, the severity and status enums, PublicIncidentFeedResponse and IncidentDetailResponse. The schemas for opening, updating, resolving and listing incidents are no longer exported.
• PublicArchetype no longer declares canvas_family, and AgentSession no longer declares pair_mode_state. The API reference leaves both out; the API may still send them, and a schema that is not .strict() ignores them.
• Added: RateLimitBucket and GetAccountRateLimitsResponse (with their schemas), the response of GET /v1/account/rate-limits, which moved here from the account module.

License

MIT.