{ "openapi": "3.1.0", "info": { "title": "Typeship", "version": "1.0.0", "description": "Resolve an OpenAPI or GraphQL Spec, diagnose it, and keep every\nselected CLI, MCP, and SDK Target current.\n\nEvery operation but one requires a bearer credential: an organization\nAPI key from the console, or an OAuth access token carrying the operation's\nread, generate, or write capability and the organization selected during\nconsent. OAuth grants cannot switch organizations after consent. A browser\nsession is not a credential for this API. The exception is POST /generate,\nwhich works anonymously with the free plan's limits.\n\nExamples use Parcel, a fictional delivery service. Replace its domains,\nrepository names, and resource identifiers with your own. The hosted\npetstore Spec is a runnable sample.\n" }, "servers": [ { "url": "https://typeship.dev/api/v1" } ], "tags": [ { "name": "projects", "description": "One API product, its Spec, shared generated-client defaults, and generation controls." }, { "name": "specs", "description": "Authored API source, patches, GraphQL settings, Diagnostic policy, and current revision." }, { "name": "spec_revisions", "description": "Immutable resolved graphs and the exact source files Projects observed and generated from." }, { "name": "targets", "description": "Independently configured CLI, MCP, and SDK products." }, { "name": "deliveries", "description": "Where each Target's package goes, such as a GitHub repository or a hosted MCP endpoint." }, { "name": "generations", "description": "One attempt to produce one Target from one immutable Spec Revision." }, { "name": "drafts", "description": "One reviewed package change per Target, its files, conflict decisions, and history recovery." }, { "name": "releases", "description": "Immutable package versions a Target released, and their registry publishing." }, { "name": "files", "description": "Immutable file snapshots from Spec Revisions, Generations, and Drafts, read in bounded chunks." }, { "name": "packages", "description": "Generate one package from an inline or URL Spec without creating a Project, and download it." }, { "name": "organization", "description": "The organization behind the presented credential and its defaults." }, { "name": "api_keys", "description": "List and revoke keys. Creation is console-only." } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Organization API key from the console (`ak_...`), or an OAuth access token with `user:org:read`, the organization selected during consent, and the capability required by the operation." } }, "schemas": { "ProjectId": { "type": "string", "pattern": "^prj_[a-z0-9]{16}$", "examples": [ "prj_4f8k2m7x9q1v6b3n" ], "description": "Unique identifier for a project." }, "GenerationId": { "type": "string", "pattern": "^gen_[a-z0-9]{16}$", "examples": [ "gen_7h2p5d9c3m8w1k6q" ], "description": "Unique identifier for a generation." }, "SpecId": { "type": "string", "pattern": "^spec_[a-z0-9]{16}$", "examples": [ "spec_2p8m4q7k1v9d6h3c" ], "description": "Unique identifier for a project's logical API Spec." }, "SpecRevisionId": { "type": "string", "pattern": "^srev_[a-z0-9]{16}$", "examples": [ "srev_6m1q8v4k2p9d7h3c" ], "description": "Unique identifier for an immutable resolved Spec Revision." }, "RequestId": { "type": "string", "pattern": "^req_[a-z0-9]{16}$", "examples": [ "req_3k8m1v6q9p2d7h4c" ], "description": "Server-generated identifier used to correlate this response with Typeship logs." }, "ResponseMetadata": { "type": "object", "required": [ "request_id" ], "properties": { "request_id": { "$ref": "#/components/schemas/RequestId" } }, "description": "Request-level metadata present at the top level of every JSON response." }, "ListObject": { "type": "string", "const": "list", "description": "Identifies a cursor-paginated collection." }, "TargetId": { "type": "string", "pattern": "^tgt_[a-z0-9]{16}$", "examples": [ "tgt_5m8q2v7k1p9d4h6c" ], "description": "Stable identifier for one configured generated product." }, "DeliveryId": { "type": "string", "pattern": "^dlv_[a-z0-9]{16}$", "examples": [ "dlv_4q8m2v7k1p9d5h6c" ] }, "DraftId": { "type": "string", "pattern": "^drf_[a-z0-9]{16}$", "examples": [ "drf_3q7m1v8k2p5d9h4c" ], "description": "Unique identifier for a Draft." }, "ReleaseId": { "type": "string", "pattern": "^rel_[a-z0-9]{16}$", "examples": [ "rel_7m2q8v4k1p9d5h6c" ] }, "GeneratorKind": { "type": "string", "enum": [ "cli", "mcp", "typescript_sdk", "python_sdk", "go_sdk" ], "description": "Package type selected by a Target. Several Targets may use the same type. The CLI is a self-contained command-line package and requires no SDK Target." }, "UrlSpecInput": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https?://", "description": "URL of an OpenAPI document, a GraphQL SDL file, or a GraphQL\nendpoint (introspected automatically). Fetched server-side.\n" }, "headers": { "type": "object", "writeOnly": true, "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 4096 }, "description": "Request headers for a protected URL. Sent on the document GET and GraphQL introspection POST, never returned or retained by one-shot generation." } } }, "InlineSpecInput": { "type": "object", "additionalProperties": false, "required": [ "inline" ], "properties": { "inline": { "type": "string", "description": "Raw Spec text (OpenAPI JSON/YAML or GraphQL SDL). Up to 4 MB, because the request body carries it; send Specs up to 10 MB with `url`." } } }, "SpecInput": { "oneOf": [ { "$ref": "#/components/schemas/UrlSpecInput" }, { "$ref": "#/components/schemas/InlineSpecInput" } ], "description": "A Spec for one-shot generation, provided as exactly one URL or inline entrypoint." }, "GenerateRequest": { "type": "object", "additionalProperties": false, "required": [ "spec", "target" ], "properties": { "spec": { "$ref": "#/components/schemas/SpecInput" }, "target": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/GeneratorKind" } }, "description": "One-shot generator descriptor; no persisted Target is created." }, "package_name": { "type": "string", "description": "npm package or Python distribution override. Valid only for the TypeScript and Python SDK targets." }, "module_path": { "type": "string", "description": "Go module path override for the generated artifact's own module. Valid only for the Go SDK and CLI Targets. Projects derive this from the Go destination repository by default." }, "config": { "$ref": "#/components/schemas/Config" } } }, "GeneratedFile": { "type": "object", "required": [ "path", "content" ], "properties": { "path": { "type": "string", "description": "Repo-relative path inside the generated package." }, "content": { "type": "string" }, "mode": { "type": "string", "enum": [ "100644", "100755" ], "default": "100644", "description": "Exact Git file mode. Omitted one-shot outputs are regular files." } } }, "GenerationWarning": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable warning code." }, "message": { "type": "string", "description": "Human-readable explanation." }, "operation": { "type": "string", "description": "METHOD/path of the affected operation, when applicable." } } }, "GenerationCoverage": { "type": "object", "required": [ "generated", "omitted", "total", "omitted_operations" ], "properties": { "generated": { "type": "integer", "minimum": 0 }, "omitted": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "omitted_operations": { "type": "array", "items": { "type": "string" }, "description": "METHOD/path identities of operations omitted from the package." }, "reason": { "type": "string", "enum": [ "anonymous", "free_plan" ], "description": "Present when a plan or anonymous limit omitted operations." }, "signup_url": { "type": "string", "format": "uri", "description": "Sign-up link for anonymous capped runs." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Upgrade link for capped signed-in runs." } } }, "FileId": { "type": "string", "pattern": "^file_[a-z0-9]{16}$", "examples": [ "file_4k8m2v7q1p9d5h6c" ], "description": "Unique identifier for one immutable file snapshot. An ID always returns the same bytes: a Spec Revision, a Generation, and each Draft side name their own file IDs, and a new Draft commit gets new IDs." }, "File": { "type": "object", "required": [ "id", "object", "path", "size_bytes", "sha256", "encoding", "mode", "created_at" ], "properties": { "id": { "$ref": "#/components/schemas/FileId" }, "object": { "type": "string", "const": "file" }, "path": { "type": "string", "description": "Path within the Spec Revision, Generation package, or Target package." }, "size_bytes": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Digest of the complete file." }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ], "description": "utf8: content is text. base64: content is base64-encoded binary bytes." }, "mode": { "oneOf": [ { "$ref": "#/components/schemas/GitFileMode" }, { "type": "null" } ], "description": "Git file mode for package files; null for Spec source files." }, "created_at": { "type": "string", "format": "date-time", "description": "When Typeship first issued this file ID." } } }, "FileResponse": { "allOf": [ { "$ref": "#/components/schemas/File" }, { "type": "object", "required": [ "content", "offset", "next_cursor" ], "properties": { "content": { "type": "string", "description": "At most 24 KiB of the file starting at offset, encoded as encoding says. Text chunks never split a character; concatenate chunks in order." }, "offset": { "type": "integer", "minimum": 0, "description": "Byte offset of this chunk in the file." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor to read the next chunk; null at the end of the file." } } }, { "$ref": "#/components/schemas/ResponseMetadata" } ] }, "FileList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor", "request_id" ], "properties": { "object": { "$ref": "#/components/schemas/ListObject" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/File" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "SpecRevisionFile": { "allOf": [ { "$ref": "#/components/schemas/File" }, { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "entrypoint", "reference", "resolved" ], "description": "entrypoint and reference: captured source files. resolved: the single normalized document Typeship generated from." } } } ] }, "SpecRevisionFileList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor", "request_id" ], "properties": { "object": { "$ref": "#/components/schemas/ListObject" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SpecRevisionFile" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "GenerationResult": { "type": "object", "required": [ "object", "files", "warnings", "coverage", "request_id" ], "properties": { "object": { "type": "string", "const": "package", "description": "One generated package. It has no ID: download it with download.url before download.expires_at." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratedFile" } }, "download": { "$ref": "#/components/schemas/GenerationDownload" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/GenerationWarning" } }, "coverage": { "$ref": "#/components/schemas/GenerationCoverage" }, "claim": { "description": "Anonymous, URL-sourced generations only. A link a signed-in person can open to turn this run into a project in their organization (same Spec, Target, and config). Lasts seven days. Null for inline Specs; absent on keyed calls.", "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "url", "expires_at" ], "properties": { "url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } ] }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "GenerationDownload": { "type": "object", "description": "Complete package ZIP from this exact result. Present on requests with Idempotency-Key, including automatic CLI, MCP, and SDK keys. Download before expires_at, verify sha256, and extract into an empty directory. Anyone with this URL can download the package; keep it private. Reading does not generate again or extend the 24-hour replay window.", "required": [ "url", "expires_at", "sha256", "size_bytes", "file_count" ], "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of the downloaded ZIP bytes." }, "size_bytes": { "type": "integer", "minimum": 0 }, "file_count": { "type": "integer", "minimum": 0 } } }, "UrlSpecSourceSettings": { "type": "object", "required": [ "url", "headers_configured" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://", "description": "URL fetched for every generation." }, "headers_configured": { "type": "boolean", "readOnly": true, "description": "Whether Typeship has stored write-only request headers for this URL." } } }, "UrlSpecSource": { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "const": "url" }, "url": { "$ref": "#/components/schemas/UrlSpecSourceSettings" } } }, "RepositoryProvider": { "type": "string", "enum": [ "github" ], "description": "GitHub is the only launch provider; the field is stable for future adapters." }, "RepositoryIdentifier": { "type": "string", "maxLength": 512, "examples": [ "parcel-example/api" ], "description": "Provider-native repository identity, opaque outside its adapter." }, "RepositorySpecSourceSettings": { "type": "object", "required": [ "provider", "identifier", "path" ], "properties": { "provider": { "$ref": "#/components/schemas/RepositoryProvider" }, "identifier": { "$ref": "#/components/schemas/RepositoryIdentifier" }, "path": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^(?!/)(?!.*\\.\\.).+$", "description": "Repository-relative Spec entrypoint." } } }, "RepositorySpecSource": { "type": "object", "required": [ "type", "repository" ], "properties": { "type": { "type": "string", "const": "repository" }, "repository": { "$ref": "#/components/schemas/RepositorySpecSourceSettings" } } }, "SpecSource": { "oneOf": [ { "$ref": "#/components/schemas/UrlSpecSource" }, { "$ref": "#/components/schemas/RepositorySpecSource" } ], "discriminator": { "propertyName": "type", "mapping": { "url": "#/components/schemas/UrlSpecSource", "repository": "#/components/schemas/RepositorySpecSource" } }, "description": "The single source of truth for where a Project's Spec lives." }, "UrlSpecSourceSettingsInput": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://", "description": "URL of an OpenAPI document, GraphQL SDL file, or GraphQL endpoint." }, "headers": { "oneOf": [ { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 4096 } }, { "type": "null" } ], "writeOnly": true, "description": "Request headers for a protected URL. Values are never returned or recorded in revision history. When updating the same URL, omit headers to preserve the stored values or pass null to remove them. Changing the URL without headers clears the old values so a credential is never forwarded to a different source." } } }, "UrlSpecSourceInput": { "type": "object", "additionalProperties": false, "required": [ "type", "url" ], "properties": { "type": { "type": "string", "const": "url" }, "url": { "$ref": "#/components/schemas/UrlSpecSourceSettingsInput" } } }, "RepositorySpecSourceSettingsInput": { "type": "object", "additionalProperties": false, "required": [ "provider", "identifier", "path" ], "properties": { "provider": { "$ref": "#/components/schemas/RepositoryProvider" }, "identifier": { "$ref": "#/components/schemas/RepositoryIdentifier" }, "path": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^(?!/)(?!.*\\.\\.).+$", "description": "Repository-relative Spec entrypoint." } } }, "RepositorySpecSourceInput": { "type": "object", "additionalProperties": false, "required": [ "type", "repository" ], "properties": { "type": { "type": "string", "const": "repository" }, "repository": { "$ref": "#/components/schemas/RepositorySpecSourceSettingsInput" } } }, "SpecSourceInput": { "oneOf": [ { "$ref": "#/components/schemas/UrlSpecSourceInput" }, { "$ref": "#/components/schemas/RepositorySpecSourceInput" } ], "discriminator": { "propertyName": "type", "mapping": { "url": "#/components/schemas/UrlSpecSourceInput", "repository": "#/components/schemas/RepositorySpecSourceInput" } } }, "SpecPatch": { "type": "object", "additionalProperties": false, "examples": [ { "op": "remove", "path": "/components/schemas/Legacy" } ], "description": "A fix applied to the resolved Spec before generation. Paths are JSON\nPointers into the document. A patch whose target no longer exists is\nskipped and reported as a warning on the generation, never silently.\n", "required": [ "op", "path" ], "properties": { "op": { "type": "string", "enum": [ "set", "append", "remove", "rename" ] }, "path": { "type": "string", "description": "JSON-Pointer-style path. Pattern segments enable bulk fixes:\n* (any child), ** (any depth), [key=value] (filter), e.g.\n/paths/**/parameters/[name=account_id]/schema/type. Renaming a\nschema under /components/schemas also rewrites its $refs.\n" }, "value": { "description": "set only; the replacement value." }, "to": { "type": [ "string", "null" ], "description": "rename only; the new key name." }, "reason": { "type": [ "string", "null" ] } } }, "DiagnosticLocation": { "type": "object", "required": [ "path", "blocking", "introduced", "suppressed" ], "description": "One exact place where a Diagnostic rule found evidence, with its own state under the Spec's Diagnostic policy.", "properties": { "blocking": { "type": "boolean", "description": "Whether this location fails the Spec's Diagnostic policy. Fix these locations to pass the policy." }, "introduced": { "type": "boolean", "description": "Whether this location is new since baseline_spec_revision_id in the Diagnostic summary. Always true when there is no baseline." }, "suppressed": { "type": "boolean", "description": "Whether a reviewed exception in the Spec's Diagnostic policy covers this location, by its path or for the whole rule. Suppressed locations never block." }, "file_path": { "type": "string", "description": "Source file path from the Spec Revision when the finding maps to a captured file." }, "file_id": { "$ref": "#/components/schemas/FileId", "description": "The captured source file, present with file_path. Read it with getFile." }, "path": { "type": "string", "description": "JSON Pointer for OpenAPI, or schema coordinate for GraphQL." }, "operation": { "type": "string", "description": "Human-readable operation coordinate when the location belongs to an operation." }, "evidence": { "type": "string", "description": "Occurrence-specific evidence. This is not a remediation instruction." } } }, "DiagnosticFix": { "type": "object", "required": [ "title", "type" ], "description": "A reviewable remediation that does not invent API behavior.", "properties": { "title": { "type": "string", "description": "Concise action for the API author." }, "type": { "type": "string", "enum": [ "spec_patch", "source_edit" ], "description": "spec_patch is an exact OpenAPI edit Typeship can derive; source_edit requires author intent or a lossless GraphQL source edit." }, "patches": { "type": "array", "items": { "$ref": "#/components/schemas/SpecPatchResponse" }, "description": "Exact patches when type is spec_patch." }, "instructions": { "type": "string", "description": "Source-level guidance when an exact patch would invent intent." } } }, "Diagnostic": { "type": "object", "required": [ "id", "object", "severity", "category", "title", "message", "surfaces", "owner_decision_required", "blocking", "introduced", "locations", "authoring_brief" ], "description": "Every occurrence of one Diagnostic rule in a Spec Revision, grouped into one decision. Diagnostics are evaluated when read, using the Spec's current patches and Diagnostic policy.", "properties": { "id": { "type": "string", "description": "Stable rule identifier, unique within a Spec Revision. Suppressions name it as rule_id." }, "object": { "type": "string", "const": "diagnostic" }, "blocking": { "type": "boolean", "description": "Whether any location fails the Spec's Diagnostic policy. Each location's blocking field names which ones. Suppressed locations and, when only_new is set, locations present in the baseline never block." }, "introduced": { "type": "boolean", "description": "Whether any location is new since baseline_spec_revision_id in the Diagnostic summary. Each location's introduced field names which ones. Always true when there is no baseline." }, "severity": { "type": "string", "enum": [ "error", "warning", "suggestion" ], "description": "Whether the rule reports invalid behavior, material risk, or an improvement." }, "category": { "type": "string", "enum": [ "correctness", "sdk_ergonomics", "agent_usability", "safety" ], "description": "Product dimension affected by the diagnostic." }, "title": { "type": "string", "description": "Concise statement of the root cause." }, "message": { "type": "string", "description": "One explanation of the finding and why it matters." }, "surfaces": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "api", "sdk", "cli", "mcp" ] }, "description": "Public surfaces affected by the root cause." }, "owner_decision_required": { "type": "boolean", "description": "Whether remediation requires intent that the Spec cannot prove." }, "locations": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/DiagnosticLocation" }, "description": "The affected coordinates, kept under one grouped Diagnostic. With a filter, only the matching locations." }, "fix": { "$ref": "#/components/schemas/DiagnosticFix" }, "authoring_brief": { "type": "string", "description": "Grounded instructions an agent can use to edit the source. The brief preserves existing behavior and requires owner input when the contract cannot prove the missing product decision." } } }, "DiagnosticSummary": { "type": "object", "required": [ "status", "error_count", "warning_count", "suggestion_count", "blocking_count", "baseline_spec_revision_id" ], "description": "Counts of grouped Diagnostics, one per rule. Retrieve the revision with include=diagnostics for each Diagnostic.", "properties": { "status": { "type": "string", "enum": [ "passed", "blocked" ], "description": "passed: no Diagnostic fails the Spec's Diagnostic policy. blocked: at least one does; retrieve with include=diagnostics and fix those marked blocking." }, "error_count": { "type": "integer", "minimum": 0, "description": "Diagnostics reporting invalid behavior." }, "warning_count": { "type": "integer", "minimum": 0, "description": "Diagnostics reporting material risk." }, "suggestion_count": { "type": "integer", "minimum": 0, "description": "Diagnostics suggesting an improvement." }, "blocking_count": { "type": "integer", "minimum": 0, "description": "Diagnostics that fail the Spec's Diagnostic policy." }, "baseline_spec_revision_id": { "oneOf": [ { "$ref": "#/components/schemas/SpecRevisionId" }, { "type": "null" } ], "description": "The previous revision of this Spec that introduced Diagnostics are compared with, or null for the first revision." } } }, "DiagnosticSuppression": { "type": "object", "additionalProperties": false, "required": [ "rule_id", "reason" ], "properties": { "rule_id": { "type": "string", "maxLength": 160 }, "path": { "type": "string", "maxLength": 4096, "description": "Exact schema coordinate. Omit only to suppress every occurrence of the rule." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The reviewed product decision behind this exception." } } }, "DiagnosticPolicy": { "type": "object", "additionalProperties": false, "description": "Source pull-request enforcement threshold, new-versus-complete baseline, and explicitly reviewed rule or location exceptions.", "required": [ "fail_on", "only_new", "suppressions" ], "properties": { "fail_on": { "type": "string", "enum": [ "never", "error", "warning" ], "default": "error", "description": "Severity threshold that fails the API change review check." }, "only_new": { "type": "boolean", "default": true, "description": "Enforce only occurrences introduced by the proposed source change." }, "suppressions": { "type": "array", "default": [], "maxItems": 100, "items": { "$ref": "#/components/schemas/DiagnosticSuppression" } } } }, "DiagnosticWarning": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "unsupported_format", "invalid_document", "invalid_patch", "no_match", "append_target_type", "rename_target_type", "rename_conflict" ] }, "message": { "type": "string" } } }, "RepositoryDeliverySettingsInput": { "type": "object", "additionalProperties": false, "required": [ "provider", "identifier" ], "properties": { "provider": { "$ref": "#/components/schemas/RepositoryProvider" }, "identifier": { "$ref": "#/components/schemas/RepositoryIdentifier" }, "directory": { "type": [ "string", "null" ] }, "package_name": { "type": [ "string", "null" ], "description": "npm or Python registry identity where applicable." }, "module_path": { "type": [ "string", "null" ], "description": "Go module identity for the Go SDK or CLI Target where applicable." }, "publish_on_merge": { "type": "boolean", "default": false, "description": "Commit repository-owned registry automation and report publication after the Draft merges." } } }, "RepositoryDeliveryInput": { "type": "object", "additionalProperties": false, "required": [ "type", "repository" ], "properties": { "type": { "type": "string", "const": "repository" }, "repository": { "$ref": "#/components/schemas/RepositoryDeliverySettingsInput" } } }, "HostedMcpDeliveryInput": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "const": "hosted_mcp" } } }, "DeliveryInput": { "oneOf": [ { "$ref": "#/components/schemas/RepositoryDeliveryInput" }, { "$ref": "#/components/schemas/HostedMcpDeliveryInput" } ], "discriminator": { "propertyName": "type", "mapping": { "repository": "#/components/schemas/RepositoryDeliveryInput", "hosted_mcp": "#/components/schemas/HostedMcpDeliveryInput" } } }, "RepositoryDeliveryCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "target_id", "type", "repository" ], "properties": { "target_id": { "$ref": "#/components/schemas/TargetId" }, "type": { "type": "string", "const": "repository" }, "repository": { "$ref": "#/components/schemas/RepositoryDeliverySettingsInput" } } }, "HostedMcpDeliveryCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "target_id", "type" ], "properties": { "target_id": { "$ref": "#/components/schemas/TargetId" }, "type": { "type": "string", "const": "hosted_mcp" } } }, "DeliveryCreateRequest": { "oneOf": [ { "$ref": "#/components/schemas/RepositoryDeliveryCreateRequest" }, { "$ref": "#/components/schemas/HostedMcpDeliveryCreateRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "repository": "#/components/schemas/RepositoryDeliveryCreateRequest", "hosted_mcp": "#/components/schemas/HostedMcpDeliveryCreateRequest" } } }, "DeliveryUpdateRequest": { "type": "object", "additionalProperties": false, "required": [ "repository" ], "properties": { "repository": { "$ref": "#/components/schemas/RepositoryDeliverySettingsInput", "description": "Replaces the complete repository settings, so omitted optional settings reset to their defaults. Only repository Deliveries have settings to update." } } }, "DeletedDelivery": { "type": "object", "required": [ "id", "object", "deleted", "request_id" ], "properties": { "id": { "$ref": "#/components/schemas/DeliveryId" }, "object": { "type": "string", "const": "delivery" }, "deleted": { "type": "boolean", "const": true }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "RepositoryDeliverySettings": { "type": "object", "required": [ "provider", "identifier", "directory", "package_name", "module_path", "publish_on_merge" ], "properties": { "provider": { "$ref": "#/components/schemas/RepositoryProvider" }, "identifier": { "$ref": "#/components/schemas/RepositoryIdentifier" }, "directory": { "type": [ "string", "null" ] }, "package_name": { "type": [ "string", "null" ] }, "module_path": { "type": [ "string", "null" ] }, "publish_on_merge": { "type": "boolean" } } }, "HostedMcpDeliverySettings": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": [ "string", "null" ], "format": "uri", "description": "Hosted MCP endpoint for this Target, or null while it is being provisioned." } } }, "RepositoryDelivery": { "type": "object", "required": [ "id", "object", "target_id", "type", "status", "repository", "issues", "required_checks", "last_event", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/DeliveryId" }, "object": { "type": "string", "const": "delivery" }, "target_id": { "$ref": "#/components/schemas/TargetId" }, "type": { "type": "string", "const": "repository" }, "status": { "type": "string", "enum": [ "active", "action_required", "disabled" ], "description": "active: the repository accepts generated changes. action_required: inspect issues for the correction. disabled: the Target is disabled and receives no changes." }, "repository": { "$ref": "#/components/schemas/RepositoryDeliverySettings" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/RepositoryDeliveryIssue" } }, "required_checks": { "type": "array", "items": { "type": "string" }, "description": "Repository check names Typeship expects before accepting a Draft." }, "last_event": { "oneOf": [ { "$ref": "#/components/schemas/RepositoryDeliveryEvent" }, { "type": "null" } ], "description": "Last observed repository event relevant to this Delivery, if available. A failed event adds an actionable issue." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RepositoryDeliveryIssue": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "app_not_installed", "repository_unreachable", "contents_write_missing", "pull_request_missing", "approval_label_missing", "check_missing", "event_failed" ] }, "message": { "type": "string", "description": "Specific customer action or repository setting to inspect." } } }, "RepositoryDeliveryEvent": { "type": "object", "required": [ "event", "status", "created_at" ], "properties": { "event": { "type": "string", "description": "Repository event type." }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "superseded" ], "description": "superseded: a newer event for the same repository replaced this one before it finished." }, "created_at": { "type": "string", "format": "date-time" } } }, "HostedMcpDelivery": { "type": "object", "required": [ "id", "object", "target_id", "type", "status", "hosted_mcp", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/DeliveryId" }, "object": { "type": "string", "const": "delivery" }, "target_id": { "$ref": "#/components/schemas/TargetId" }, "type": { "type": "string", "const": "hosted_mcp" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "active: the endpoint serves the Target's latest accepted package. disabled: the Target is disabled and the endpoint is paused." }, "hosted_mcp": { "$ref": "#/components/schemas/HostedMcpDeliverySettings" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Delivery": { "oneOf": [ { "$ref": "#/components/schemas/RepositoryDelivery" }, { "$ref": "#/components/schemas/HostedMcpDelivery" } ], "discriminator": { "propertyName": "type", "mapping": { "repository": "#/components/schemas/RepositoryDelivery", "hosted_mcp": "#/components/schemas/HostedMcpDelivery" } } }, "DeliveryResponse": { "type": "object", "description": "repository is present for a repository Delivery, with issues, required_checks, and last_event; hosted_mcp is present for a hosted_mcp Delivery.", "required": [ "id", "object", "target_id", "type", "status", "created_at", "updated_at", "request_id" ], "properties": { "id": { "$ref": "#/components/schemas/DeliveryId" }, "object": { "type": "string", "const": "delivery" }, "target_id": { "$ref": "#/components/schemas/TargetId" }, "type": { "type": "string", "enum": [ "repository", "hosted_mcp" ] }, "status": { "type": "string", "enum": [ "active", "action_required", "disabled" ] }, "repository": { "$ref": "#/components/schemas/RepositoryDeliverySettings" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/RepositoryDeliveryIssue" } }, "required_checks": { "type": "array", "items": { "type": "string" } }, "last_event": { "oneOf": [ { "$ref": "#/components/schemas/RepositoryDeliveryEvent" }, { "type": "null" } ] }, "hosted_mcp": { "$ref": "#/components/schemas/HostedMcpDeliverySettings" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "TargetChecks": { "type": "object", "additionalProperties": false, "properties": { "generated": { "type": "array", "uniqueItems": true, "default": [ "build", "package", "public_entrypoint" ], "items": { "type": "string", "enum": [ "build", "package", "public_entrypoint" ] } }, "repository_required": { "type": "array", "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "customer": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "command" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "command": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } }, "description": "Required checks run against the code in the Draft. Generated checks and customer commands share one reproducible workflow; repository_required names existing repository checks. Supplying checks replaces all settings. Omitted generated restores build, package, and public_entrypoint; omitted repository_required and customer restore empty lists. An empty object restores these defaults. An empty array clears the corresponding list." }, "TargetCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "project_id", "name", "type" ], "properties": { "project_id": { "$ref": "#/components/schemas/ProjectId" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "type": { "$ref": "#/components/schemas/GeneratorKind", "example": "cli" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "default": "active" }, "release_channel": { "type": "string", "enum": [ "stable", "prerelease" ], "default": "stable" }, "checks": { "$ref": "#/components/schemas/TargetChecks" }, "config": { "oneOf": [ { "$ref": "#/components/schemas/TargetConfig" }, { "type": "null" } ], "description": "Target-specific overrides merged over Project.config. GraphQL settings are rejected here and belong to the Spec." }, "deliveries": { "type": "array", "maxItems": 2, "items": { "$ref": "#/components/schemas/DeliveryInput" } } } }, "InitialTargetFields": { "type": "object", "additionalProperties": false, "required": [ "name", "type" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "type": { "$ref": "#/components/schemas/GeneratorKind", "example": "cli" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "default": "active" }, "release_channel": { "type": "string", "enum": [ "stable", "prerelease" ], "default": "stable" }, "checks": { "$ref": "#/components/schemas/TargetChecks" }, "config": { "oneOf": [ { "$ref": "#/components/schemas/TargetConfig" }, { "type": "null" } ], "description": "Target-specific overrides merged over Project.config. GraphQL settings are rejected here and belong to the Spec." }, "deliveries": { "type": "array", "maxItems": 2, "items": { "$ref": "#/components/schemas/DeliveryInput" } } } }, "TargetUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "release_channel": { "type": "string", "enum": [ "stable", "prerelease" ] }, "checks": { "$ref": "#/components/schemas/TargetChecks" }, "config": { "oneOf": [ { "$ref": "#/components/schemas/TargetConfig" }, { "type": "null" } ], "description": "Replaces the complete stored override object. Send null or an empty object to resume Project inheritance. Effective values merge over Project.config; GraphQL settings belong to the Spec." } } }, "Target": { "type": "object", "description": "All Targets follow reviewed SemVer. Before 1.0.0, breaking changes require a minor version; the policy is fixed rather than configurable.", "required": [ "id", "object", "project_id", "spec_id", "name", "type", "status", "release_channel", "version_current", "draft_id", "checks", "config", "deliveries", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/TargetId" }, "object": { "type": "string", "const": "target" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "spec_id": { "$ref": "#/components/schemas/SpecId" }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/GeneratorKind", "example": "cli" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "release_channel": { "type": "string", "enum": [ "stable", "prerelease" ] }, "version_current": { "type": [ "string", "null" ], "readOnly": true, "description": "Read-only version of the Target's latest release, or null before its first release. Publishing status is separate; inspect the release for its results." }, "draft_id": { "$ref": "#/components/schemas/DraftId", "readOnly": true, "description": "The Target's open Draft. After a merge it names the next Draft." }, "checks": { "$ref": "#/components/schemas/TargetChecksResponse" }, "config": { "oneOf": [ { "$ref": "#/components/schemas/TargetConfigResponse" }, { "type": "null" } ], "description": "Target-specific overrides merged over Project.config. GraphQL settings are Spec-owned and never appear here." }, "deliveries": { "type": "array", "maxItems": 2, "items": { "$ref": "#/components/schemas/Delivery" }, "description": "At most one repository and one hosted MCP Delivery." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "TargetResponse": { "allOf": [ { "$ref": "#/components/schemas/Target" }, { "$ref": "#/components/schemas/ResponseMetadata" } ] }, "DeliveryList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor", "request_id" ], "properties": { "object": { "$ref": "#/components/schemas/ListObject" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "DraftList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor", "request_id" ], "properties": { "object": { "$ref": "#/components/schemas/ListObject" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Draft" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "TargetList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor", "request_id" ], "properties": { "object": { "$ref": "#/components/schemas/ListObject" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Target" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "Release": { "type": "object", "required": [ "id", "object", "target_id", "generation_id", "version", "release_channel", "origin", "repository", "spec_revision_id", "commit_sha", "checks", "approvals", "import_provenance", "publications", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/ReleaseId" }, "object": { "type": "string", "const": "release" }, "target_id": { "$ref": "#/components/schemas/TargetId" }, "generation_id": { "oneOf": [ { "$ref": "#/components/schemas/GenerationId" }, { "type": "null" } ], "description": "Null only for a verified release imported during package adoption." }, "origin": { "type": "string", "enum": [ "typeship", "imported" ] }, "version": { "type": "string", "description": "Immutable package version released from this Target." }, "release_channel": { "type": "string", "enum": [ "stable", "prerelease" ], "description": "The Target's release_channel when this version was released." }, "repository": { "oneOf": [ { "$ref": "#/components/schemas/RepositoryReferenceResponse" }, { "type": "null" } ] }, "spec_revision_id": { "oneOf": [ { "$ref": "#/components/schemas/SpecRevisionId" }, { "type": "null" } ] }, "commit_sha": { "type": "string", "pattern": "^[0-9a-fA-F]{40}$", "description": "Git commit containing the accepted package. Compare it with the Delivery repository history or checked-out commit." }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/PackageCheck" } }, "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/CompatibilityApproval" } }, "import_provenance": { "type": [ "object", "null" ], "description": "For an adopted Release, compare the tag and registry URL with the published package and its artifact digest. Null for a Release created by Typeship.", "required": [ "tag", "registry_url", "artifact_digest", "imported_at" ], "properties": { "tag": { "type": [ "string", "null" ], "description": "Git tag to compare with the repository release, if available." }, "registry_url": { "type": [ "string", "null" ], "format": "uri", "description": "Published package page to inspect, if available." }, "artifact_digest": { "type": [ "string", "null" ], "description": "Published artifact digest to compare with registry metadata, if available." }, "imported_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When Typeship recorded the adopted package." } } }, "publications": { "type": "array", "items": { "$ref": "#/components/schemas/Publication" }, "description": "One entry per destination Typeship has attempted to publish. Empty when publishing is off for the Target's repository Delivery." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "When a Publication of this release last changed. The version, commit, and checks never change after the release is created." }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "ReleaseResponse": { "allOf": [ { "$ref": "#/components/schemas/Release" }, { "$ref": "#/components/schemas/ResponseMetadata" } ] }, "ReleaseList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor", "request_id" ], "properties": { "object": { "$ref": "#/components/schemas/ListObject" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Release" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "Publication": { "type": "object", "description": "One destination's publishing progress for its Release. It has no ID; read it on the Release.", "required": [ "type", "status", "attempt", "run_url", "registry_url", "artifact_digest", "errors", "started_at", "finished_at", "runtime_ms", "created_at", "updated_at" ], "properties": { "type": { "type": "string", "enum": [ "github", "npm", "pypi", "go", "mcp" ], "description": "Where the release is published. github is the repository's GitHub Release; the others are package registries." }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ], "description": "queued: the repository workflow has not started this destination; get the Publication or its Release again. running: the workflow is publishing; get it again. completed: the package is published at registry_url. failed: read errors, correct the cause, then retry the Release. Lifecycle events are publication.running, publication.completed, and publication.failed." }, "attempt": { "type": "integer", "minimum": 0 }, "run_url": { "type": [ "string", "null" ], "format": "uri" }, "registry_url": { "type": [ "string", "null" ], "format": "uri" }, "artifact_digest": { "type": [ "string", "null" ] }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/DomainError" }, "description": "Recorded failures. Empty when this resource has no recorded failure." }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "runtime_ms": { "type": [ "integer", "null" ], "minimum": 0, "description": "Milliseconds from started_at to finished_at; null until the attempt finishes." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DraftStatus": { "type": "string", "enum": [ "idle", "working", "action_required", "ready", "merged" ], "description": "idle: the open Draft has no pending change; generate the Target to start one. working: Typeship is generating, carrying repository edits forward, applying decisions, or checking the Draft; retrieve it again. action_required: use the typed reason to find the customer's next action. ready: required checks passed on head_sha; merge the pull request. merged: the pull request merged and the Draft is final; retrieve the Target for the draft_id of its next Draft." }, "DraftActionReason": { "type": "string", "enum": [ "conflict", "checks_failed", "review_failed", "checks_unavailable", "history_rewritten" ], "description": "conflict: resolve the listed files. checks_failed: correct failed package checks. review_failed: correct the Draft title or version. checks_unavailable: restore a required check. history_rewritten: review the affected files and approve recovery." }, "DraftConflicts": { "type": "object", "required": [ "total", "decided" ], "properties": { "total": { "type": "integer", "minimum": 1, "description": "Conflicts in the current merge stage." }, "decided": { "type": "integer", "minimum": 0, "description": "Conflicts with a saved decision for head_sha." } } }, "DraftHistoryRecovery": { "type": "object", "required": [ "default_sha", "head_sha", "preserved_branch" ], "description": "The approval inputs for a default-branch history rewrite.", "properties": { "default_sha": { "type": "string", "description": "Rewritten default-branch commit. Send it as expected_default_sha." }, "head_sha": { "type": [ "string", "null" ], "description": "Draft commit Typeship last observed. Send it as expected_head_sha." }, "preserved_branch": { "type": [ "string", "null" ], "description": "Existing Draft branch that stays available after recovery opens a new Draft." } } }, "DraftCompatibility": { "type": "object", "description": "Comparison of the Draft's head_sha with the latest release.", "required": [ "api", "package" ], "properties": { "api": { "type": "string", "enum": [ "compatible", "breaking", "unknown" ], "description": "API surface comparison. unknown means analysis is unavailable." }, "package": { "type": "string", "enum": [ "compatible", "breaking", "unknown" ], "description": "Package and supported SDK source comparison. unknown means analysis is incomplete or unavailable." } } }, "DraftVersion": { "type": "object", "description": "How version_next relates to the assessed change.", "required": [ "bump_required", "correct", "previous" ], "properties": { "bump_required": { "type": [ "string", "null" ], "enum": [ "major", "minor", "patch", null ], "description": "Minimum assessed version bump. Approval never waives an insufficient bump. Null when no bump has been determined." }, "correct": { "type": [ "boolean", "null" ], "description": "Whether version_next satisfies the assessed change. Null when no verdict is available." }, "previous": { "type": [ "string", "null" ], "description": "Latest release version used for the comparison. Null before the first release." } } }, "Draft": { "type": "object", "if": { "properties": { "status": { "const": "action_required" } }, "required": [ "status" ] }, "then": { "required": [ "reason" ] }, "else": { "not": { "required": [ "reason" ] } }, "description": "One reviewed package change for a Target. A Target has one open Draft, named by its draft_id; when the pull request merges, the Draft becomes merged and final, and the Target opens a new Draft with a new ID.", "required": [ "id", "object", "target_id", "project_id", "status", "version_next", "version_source", "compatibility", "version", "errors", "checks", "changes", "head_sha", "pull_request", "generation_id", "release_id", "conflicts", "customized_files", "history_recovery", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/DraftId" }, "object": { "type": "string", "const": "draft" }, "target_id": { "$ref": "#/components/schemas/TargetId" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "status": { "$ref": "#/components/schemas/DraftStatus" }, "reason": { "$ref": "#/components/schemas/DraftActionReason", "description": "Present and required when status is action_required; absent otherwise." }, "version_next": { "type": [ "string", "null" ], "description": "Next version for this Draft, or null before a version is selected." }, "version_source": { "type": [ "string", "null" ], "enum": [ "automatic", "console", "api", "github", null ], "description": "Where version_next was selected; null once the Draft merged." }, "compatibility": { "oneOf": [ { "$ref": "#/components/schemas/DraftCompatibility" }, { "type": "null" } ], "description": "Null until the Draft has a generated change, and on a merged Draft." }, "version": { "oneOf": [ { "$ref": "#/components/schemas/DraftVersion" }, { "type": "null" } ], "description": "Null until the Draft has a generated change, and on a merged Draft." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "description": "What blocks the Draft, one entry per finding, each with a code and suggested_action. Empty unless status is action_required." }, "changes": { "type": [ "object", "null" ], "properties": { "changelog": { "type": [ "string", "null" ], "description": "Cumulative changelog against the latest release." }, "breaking_count": { "type": [ "integer", "null" ], "minimum": 0 } } }, "head_sha": { "type": [ "string", "null" ], "description": "Draft commit that compatibility, version, checks, and conflicts describe. Send it as expected_head_sha when resolving or discarding." }, "pull_request": { "oneOf": [ { "type": "object", "required": [ "url", "number" ], "properties": { "url": { "type": "string", "format": "uri" }, "number": { "type": "integer", "minimum": 1 } } }, { "type": "null" } ], "description": "The Draft pull request in the destination repository, or null before one is opened." }, "generation_id": { "oneOf": [ { "$ref": "#/components/schemas/GenerationId" }, { "type": "null" } ], "description": "Generation whose package this Draft contains." }, "release_id": { "oneOf": [ { "$ref": "#/components/schemas/ReleaseId" }, { "type": "null" } ], "description": "Release this Draft created when it merged; null while open, or when a merge changed only tests or checks." }, "created_at": { "type": "string", "format": "date-time", "description": "When the Draft opened." }, "updated_at": { "type": "string", "format": "date-time" }, "conflicts": { "oneOf": [ { "$ref": "#/components/schemas/DraftConflicts" }, { "type": "null" } ], "description": "Conflict counts for the current merge stage; null when the Draft has no conflicts." }, "customized_files": { "type": [ "integer", "null" ], "minimum": 0, "description": "Files where the Draft differs from the last accepted package; null until the Draft is integrated." }, "history_recovery": { "oneOf": [ { "$ref": "#/components/schemas/DraftHistoryRecovery" }, { "type": "null" } ], "description": "Present only while status is action_required and reason is history_rewritten." }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/PackageCheck" } } } }, "DraftResponse": { "allOf": [ { "$ref": "#/components/schemas/Draft" }, { "$ref": "#/components/schemas/ResponseMetadata" } ] }, "DraftUpdateRequest": { "type": "object", "additionalProperties": false, "required": [ "version_next" ], "properties": { "version_next": { "type": [ "string", "null" ], "description": "Exact SemVer, or null to return to automatic selection." } } }, "PackageCheck": { "type": "object", "required": [ "name", "source", "required", "status", "reason", "commit_sha", "url", "observed_at" ], "properties": { "name": { "type": "string" }, "source": { "type": "string", "enum": [ "typeship", "customer", "repository", "compatibility" ] }, "required": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "passed", "failed", "not_assessed" ] }, "reason": { "type": "string" }, "commit_sha": { "type": "string" }, "url": { "type": [ "string", "null" ], "format": "uri" }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CompatibilityApproval": { "type": "object", "required": [ "source", "reason", "approved_by", "approved_sha", "approved_at" ], "properties": { "source": { "type": "string", "enum": [ "source_pr", "draft_pr" ] }, "reason": { "type": "string" }, "approved_by": { "type": "string" }, "approved_sha": { "type": "string" }, "approved_at": { "type": "string", "format": "date-time" } } }, "TargetAdoption": { "type": "object", "additionalProperties": false, "required": [ "version", "tag" ], "properties": { "version": { "type": "string", "description": "Exact already-published package version to make the latest release." }, "tag": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Immutable repository tag containing the matching package source." } } }, "SpecFields": { "type": "object", "additionalProperties": false, "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/SpecSourceInput" }, "patches": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/SpecPatch" }, "default": [] }, "graphql": { "oneOf": [ { "$ref": "#/components/schemas/GraphqlSettings" }, { "type": "null" } ], "description": "GraphQL-only endpoint, auth, environment, title, and scalar settings." }, "diagnostic_policy": { "$ref": "#/components/schemas/DiagnosticPolicy" } } }, "Spec": { "type": "object", "required": [ "id", "object", "project_id", "source", "format", "patches", "graphql", "diagnostic_policy", "revision_latest_id", "created_at", "updated_at", "request_id" ], "properties": { "id": { "$ref": "#/components/schemas/SpecId" }, "object": { "type": "string", "const": "spec" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "source": { "$ref": "#/components/schemas/SpecSource" }, "format": { "type": [ "string", "null" ], "enum": [ "openapi", "graphql", null ] }, "patches": { "type": "array", "items": { "$ref": "#/components/schemas/SpecPatchResponse" } }, "graphql": { "oneOf": [ { "$ref": "#/components/schemas/GraphqlSettingsResponse" }, { "type": "null" } ] }, "diagnostic_policy": { "$ref": "#/components/schemas/DiagnosticPolicyResponse" }, "revision_latest_id": { "oneOf": [ { "$ref": "#/components/schemas/SpecRevisionId" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "SpecUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Omitted fields remain unchanged. Supplied objects and arrays replace the whole field. URL source headers are preserved when the URL is unchanged and headers are omitted; null or empty headers clear them.", "properties": { "source": { "$ref": "#/components/schemas/SpecSourceInput" }, "patches": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/SpecPatch" }, "description": "Replace all patches in order. An empty array removes every patch; null is invalid." }, "graphql": { "description": "Replace all GraphQL settings. Null or an empty object clears them.", "oneOf": [ { "$ref": "#/components/schemas/GraphqlSettings" }, { "type": "null" } ] }, "diagnostic_policy": { "$ref": "#/components/schemas/DiagnosticPolicy", "description": "Replace the complete policy and suppression list. Null and an empty object are invalid." } } }, "Project": { "type": "object", "description": "Project-owned identity, Spec reference, generation controls, and shared configuration. Targets and Deliveries are available only through their canonical Target endpoints.", "required": [ "id", "object", "name", "spec_id", "auto_generate", "config", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/ProjectId", "readOnly": true }, "object": { "type": "string", "const": "project", "readOnly": true }, "name": { "type": "string", "maxLength": 80 }, "spec_id": { "$ref": "#/components/schemas/SpecId" }, "auto_generate": { "type": "boolean", "description": "Regenerate when the Spec or saved configuration changes. Enabled by default for new Projects. Set false to generate only when requested." }, "config": { "oneOf": [ { "$ref": "#/components/schemas/ProjectConfigResponse" }, { "type": "null" } ], "description": "Shared defaults inherited by every Target. A Target's config overrides these defaults; GraphQL settings remain Spec-owned." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the project configuration last changed." }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "ProjectResponse": { "allOf": [ { "$ref": "#/components/schemas/Project" }, { "$ref": "#/components/schemas/ResponseMetadata" } ] }, "CreateProjectRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "spec", "targets" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "spec": { "$ref": "#/components/schemas/SpecFields" }, "targets": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/InitialTargetFields" }, "description": "Initial first-class Targets. More than one may use the same generator with different identities or Deliveries." }, "auto_generate": { "type": "boolean", "default": true, "description": "Whether Typeship should regenerate automatically when the source or saved configuration changes." }, "config": { "oneOf": [ { "$ref": "#/components/schemas/ProjectConfig" }, { "type": "null" } ], "description": "Shared defaults inherited by every Target. GraphQL settings belong in spec.graphql." } } }, "UpdateProjectRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "auto_generate": { "type": "boolean" }, "config": { "oneOf": [ { "$ref": "#/components/schemas/ProjectConfig" }, { "type": "null" } ], "description": "Replaces the Project's shared Target defaults. Send null to clear them." } } }, "Organization": { "type": "object", "description": "The organization an API key belongs to. Members share its projects, keys, and plan; sign-in identity is not part of the API.", "required": [ "id", "object", "name", "plan", "created_at", "updated_at", "request_id" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "Opaque, output-only organization identifier. Copy it unchanged; its format is not a contract." }, "object": { "type": "string", "const": "organization" }, "name": { "type": "string", "description": "The organization's display name." }, "plan": { "type": "string", "enum": [ "free", "pro", "enterprise" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "OAuthServer": { "type": "object", "additionalProperties": false, "description": "Authorization-server metadata used by generated OAuth flows. Secrets and runtime credentials are never accepted here.", "properties": { "issuer": { "type": [ "string", "null" ], "format": "uri", "description": "Exact authorization-server issuer, including any tenant path." }, "discovery_url": { "type": [ "string", "null" ], "format": "uri", "description": "Exact metadata URL when it cannot be derived from the issuer." }, "authorization_url": { "type": [ "string", "null" ], "format": "uri", "description": "Authorization endpoint override." }, "token_url": { "type": [ "string", "null" ], "format": "uri", "description": "Token endpoint override." }, "device_authorization_url": { "type": [ "string", "null" ], "format": "uri", "description": "Device-authorization endpoint override." }, "scopes": { "type": [ "array", "null" ], "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "^\\S+$" }, "description": "Default scopes requested during login." }, "audience": { "type": [ "string", "null" ], "description": "Default audience included in authorization and token requests." }, "resource": { "type": [ "string", "null" ], "format": "uri", "description": "Protected API resource included in authorization and token requests." } } }, "OAuthApplication": { "type": "object", "additionalProperties": false, "required": [ "client_id" ], "description": "OAuth application available to generated products. Public clients support interactive login; confidential clients support runtime-supplied machine credentials. Client secrets are never stored.", "properties": { "client_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "OAuth client identifier." }, "login_method": { "type": [ "string", "null" ], "enum": [ "browser", "device", null ], "description": "Interactive login method. Browser login uses Authorization Code with PKCE." }, "client_auth_method": { "type": [ "string", "null" ], "enum": [ "post", "basic", null ], "description": "How a runtime-supplied client secret is sent for machine grants." }, "redirect_uri": { "type": [ "string", "null" ], "format": "uri", "description": "Loopback callback URL for browser login." }, "organization_parameter": { "type": [ "string", "null" ], "enum": [ "organization", "organization_id", null ], "description": "Provider parameter used to request an organization during browser login." } } }, "IdentityVerification": { "description": "Authenticated identity read used to verify a login before it is saved. Operation is auto-detected when omitted or null. At least one of subject_field, account_field, or organization_field must be a non-null JSON Pointer. Null clears an individual mapping while another remains. Set identity_verification itself to null to remove the whole policy.", "example": { "subject_field": "/id", "account_field": "/account_id", "organization_field": "/organization_id" }, "allOf": [ { "type": "object", "additionalProperties": false, "properties": { "operation": { "type": [ "string", "null" ], "maxLength": 2000, "pattern": "^[\\w$]+\\.[\\w$]+$", "description": "resource.method of a safe identity read with no required arguments." }, "subject_field": { "type": [ "string", "null" ], "maxLength": 512, "pattern": "^/(?:[^~\\x00-\\x1f\\x7f]|~[01])*$", "description": "JSON Pointer to the stable caller ID in the identity response.", "example": "/id" }, "account_field": { "type": [ "string", "null" ], "maxLength": 512, "pattern": "^/(?:[^~\\x00-\\x1f\\x7f]|~[01])*$", "description": "JSON Pointer to the customer account ID.", "example": "/account_id" }, "organization_field": { "type": [ "string", "null" ], "maxLength": 512, "pattern": "^/(?:[^~\\x00-\\x1f\\x7f]|~[01])*$", "description": "JSON Pointer to the customer organization ID.", "example": "/organization_id" } } }, { "anyOf": [ { "required": [ "subject_field" ], "properties": { "subject_field": { "type": "string" } } }, { "required": [ "account_field" ], "properties": { "account_field": { "type": "string" } } }, { "required": [ "organization_field" ], "properties": { "organization_field": { "type": "string" } } } ] } ] }, "AuthenticationEnvironment": { "type": "object", "additionalProperties": false, "description": "OAuth application and request-value overrides for one named API environment.", "properties": { "oauth_application": { "type": [ "string", "null" ], "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "scopes": { "type": [ "array", "null" ], "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "^\\S+$" } }, "audience": { "type": [ "string", "null" ] }, "resource": { "type": [ "string", "null" ], "format": "uri" } } }, "AuthenticationConfig": { "type": "object", "additionalProperties": false, "description": "Public authentication defaults for generated clients and tools. Stored Projects own the OAuth server, application catalog, and identity policy; one-shot generation accepts the same shape for one run. Runtime credentials and client secrets are never accepted.", "properties": { "oauth_server": { "oneOf": [ { "$ref": "#/components/schemas/OAuthServer" }, { "type": "null" } ] }, "oauth_applications": { "type": [ "object", "null" ], "maxProperties": 20, "propertyNames": { "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "additionalProperties": { "$ref": "#/components/schemas/OAuthApplication" }, "description": "OAuth applications keyed by a stable name." }, "oauth_application": { "type": [ "string", "null" ], "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "description": "Default OAuth application used by generated products." }, "identity_verification": { "oneOf": [ { "$ref": "#/components/schemas/IdentityVerification" }, { "type": "null" } ] }, "approval_url": { "type": [ "string", "null" ], "format": "uri", "description": "Base URL of a custom browser-approval backend implementing the start, status, and revoke contract. Used only when OAuth is not configured." }, "environments": { "type": [ "object", "null" ], "maxProperties": 20, "propertyNames": { "pattern": "^[A-Za-z_$][A-Za-z0-9_$]{0,127}$" }, "additionalProperties": { "$ref": "#/components/schemas/AuthenticationEnvironment" }, "description": "Authentication selections keyed by generated API environment name." }, "credential_variables": { "type": [ "object", "null" ], "maxProperties": 20, "propertyNames": { "minLength": 1, "maxLength": 200 }, "additionalProperties": { "oneOf": [ { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]{0,127}$" }, { "type": "object", "additionalProperties": false, "required": [ "username", "password" ], "properties": { "username": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]{0,127}$" }, "password": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]{0,127}$" } } } ] }, "description": "Environment variables the generated CLI, MCP server, and SDK environment fallbacks read, keyed by security scheme name. A string names the token or key variable; a Basic scheme takes { username, password }. Wins over the scheme's x-typeship-env extension. Without either, names derive from the package and scheme." }, "credential_parameters": { "type": [ "object", "null" ], "maxProperties": 200, "propertyNames": { "minLength": 1, "maxLength": 500 }, "additionalProperties": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "boolean" } }, "description": "Whether a parameter carries the operation's credential, keyed by operationId, \"METHOD /path\", or \"*\" for every operation, then by the parameter's wire name. true leaves the parameter out of generated signatures, CLI flags, and MCP tool input, because the configured credential already reaches the API; false keeps it. Wins over the parameter's x-typeship-credential extension and the generator's inference." } } }, "TargetAuthenticationEnvironment": { "type": "object", "additionalProperties": false, "properties": { "oauth_application": { "type": [ "string", "null" ], "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$" } } }, "TargetAuthenticationConfig": { "type": "object", "additionalProperties": false, "description": "Selects a Project OAuth application for one Target. OAuth server metadata, applications, and identity policy remain Project-owned.", "properties": { "oauth_application": { "type": [ "string", "null" ], "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "description": "Project OAuth application to use. Omit to inherit the Project default." }, "environments": { "type": [ "object", "null" ], "maxProperties": 20, "propertyNames": { "pattern": "^[A-Za-z_$][A-Za-z0-9_$]{0,127}$" }, "additionalProperties": { "$ref": "#/components/schemas/TargetAuthenticationEnvironment" }, "description": "Project OAuth application selections keyed by API environment." } } }, "CliBehavior": { "type": "object", "additionalProperties": false, "description": "How the generated CLI behaves. Part of Config.", "properties": { "command_name": { "type": [ "string", "null" ], "description": "Command users run, independent of how the CLI is distributed." }, "changelog_url": { "type": [ "string", "null" ], "description": "Public HTTP(S) URL read by the optional changelog command in generated CLIs. Supports UTF-8 Markdown, plain text, and static HTML; embedded credentials are not allowed. Omit or clear to disable, then regenerate." }, "support_url": { "type": [ "string", "null" ], "description": "Where the generated CLI's feedback command sends users. GitHub issues/new URLs get a prefilled title and environment details." }, "mcp_url": { "type": [ "string", "null" ], "description": "Fallback MCP endpoint used by the generated CLI when the Project has no Typeship-hosted MCP endpoint. A hosted endpoint takes precedence over this URL." }, "skills_repo": { "type": [ "string", "null" ], "description": "Repository in owner/name format that the generated CLI's init command offers for skill installation." } } }, "TargetCliBehavior": { "type": "object", "additionalProperties": false, "description": "How the generated CLI behaves. Part of Config.", "properties": { "command_name": { "type": [ "string", "null" ], "description": "Command users run, independent of how the CLI is distributed." }, "changelog_url": { "type": [ "string", "null" ], "description": "Public HTTP(S) URL read by the optional changelog command in generated CLIs. Supports UTF-8 Markdown, plain text, and static HTML; embedded credentials are not allowed. Omit or clear to disable, then regenerate." }, "support_url": { "type": [ "string", "null" ], "description": "Where the generated CLI's feedback command sends users. GitHub issues/new URLs get a prefilled title and environment details." }, "mcp_url": { "type": [ "string", "null" ], "description": "Fallback MCP endpoint used by the generated CLI when the Project has no Typeship-hosted MCP endpoint. A hosted endpoint takes precedence over this URL." }, "skills_repo": { "type": [ "string", "null" ], "description": "Repository in owner/name format that the generated CLI's init command offers for skill installation." }, "relay": { "type": "boolean", "description": "Enable webhook relay sessions for this CLI Target. Requires Pro. Turning it off prevents new sessions." }, "unit_tests": { "type": "boolean", "description": "Also generate unit tests for the helper code a CLI shares, such as raw API path checks, saved credentials, and MCP client configuration. Applies to cli Targets. Off by default; tests for the generated commands are always included." } } }, "McpBehavior": { "type": "object", "additionalProperties": false, "description": "How generated MCP servers and the Typeship-hosted endpoint behave. Part of Config.", "properties": { "registry_name": { "type": [ "string", "null" ], "description": "Stable official MCP registry name, independent of the server runtime." }, "access": { "type": "object", "additionalProperties": false, "required": [ "issuer", "resource" ], "description": "Authorization for callers connecting to a generated MCP server deployed over HTTP. The hosting application resolves upstream API credentials separately at runtime. This setting does not apply to the Typeship-hosted endpoint.", "properties": { "issuer": { "type": "string", "format": "uri", "description": "Exact issuer allowed to sign MCP connection tokens." }, "resource": { "type": "string", "format": "uri", "description": "Canonical public URL of the self-hosted MCP endpoint that connection tokens must target." }, "jwks_url": { "type": "string", "format": "uri", "description": "Public signing-key endpoint. Omit to discover it from the issuer." }, "scopes": { "type": "array", "maxItems": 20, "items": { "type": "string" }, "description": "Minimum scopes required to connect to the self-hosted MCP server." } } }, "tool_mode": { "type": "string", "enum": [ "auto", "operations", "meta" ], "description": "MCP tool shape. meta collapses per-operation tools into search_docs, read_docs, and execute so large APIs don't flood an agent's context window. Auto considers the serialized tool schemas, switching near 10k tokens or above 100 operations." }, "instructions": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Guidance appended to the MCP server's instructions, which agents read once when they connect (server/discover): what to call first, conventions the spec does not state, what not to do. Carried by the package's server and the hosted endpoint alike." }, "tool_descriptions": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 600 }, "maxProperties": 200, "description": "Hand-written MCP tool descriptions keyed by operationId or \"METHOD /path\". Each replaces the text typeship derives for that operation (summary, first sentence, method and path, deprecation and auth notes). For flows the spec cannot describe, such as a multi-step upload. Keys that match no operation are reported as generation warnings." }, "reference_resolvers": { "type": "object", "maxProperties": 200, "description": "Exact name-or-ID resolver overrides keyed first by the target operationId or \"METHOD /path\", then by its wire argument name. A resolver names one read collection operation plus 1-4 item fields to match case-insensitively; false opts that argument out of strict inference.", "additionalProperties": { "type": "object", "maxProperties": 20, "additionalProperties": { "oneOf": [ { "type": "boolean", "enum": [ false ] }, { "type": "object", "additionalProperties": false, "required": [ "via", "match" ], "properties": { "via": { "type": "string", "maxLength": 200, "description": "OperationId, \"METHOD /path\", MCP tool name, or dotted resource.method of the list operation." }, "match": { "type": "array", "minItems": 1, "maxItems": 4, "uniqueItems": true, "items": { "type": "string", "maxLength": 100 }, "description": "Item fields compared exactly and case-insensitively, such as name, slug, key, or email." }, "id": { "type": "string", "maxLength": 100, "description": "Item field substituted into the requested argument. Defaults to id." } } } ] } } } } }, "ReadmeBehavior": { "type": "object", "additionalProperties": false, "description": "Generated README behavior. Part of Config.", "properties": { "quickstart_operation": { "type": [ "string", "null" ], "maxLength": 500, "description": "operationId or \"METHOD /path\" to feature as the README's first API call. It must be present in the generated package and callable with no required input beyond path placeholders. Missing or unsuitable choices produce a warning and use the automatic example." } } }, "PackageBehavior": { "type": "object", "additionalProperties": false, "description": "Published-package metadata the API spec does not own. Repository is derived from each destination.", "properties": { "title": { "type": [ "string", "null" ], "maxLength": 100, "description": "The API's name as generated READMEs, AGENTS.md, package descriptions, and help text show it, such as \"Parcel\" for a Spec titled \"Parcel - Public API\". Display only: package, client, and command names still come from the Spec. Defaults to the Spec title with common noise removed (\"Parcel - API\" shows as Parcel)." }, "homepage": { "type": [ "string", "null" ], "description": "Homepage written into registry metadata." }, "license": { "type": [ "string", "null" ], "maxLength": 200, "description": "SPDX identifier written into registry metadata. Defaults to info.license." }, "license_text": { "type": [ "string", "null" ], "maxLength": 100000, "description": "Exact LICENSE file contents. Supply this for licences the engine does not build in; MIT is built in when copyright is also set." }, "copyright": { "type": [ "string", "null" ], "maxLength": 200, "description": "Copyright line used in generated license files." }, "go_package_name": { "type": [ "string", "null" ], "description": "Go identifier when the destination repository name is unsuitable." } } }, "Config": { "type": "object", "additionalProperties": false, "description": "Everything Typeship needs beyond the Spec, in one object: generation customization (globals, retries, pagination, readme) and how the generated tooling behaves (cli, mcp, package, docs_url). Plain configuration. Typeship never requires vendor extensions inside the Spec itself. One-shot generation also accepts GraphQL settings here; stored projects keep those settings on their Spec.", "properties": { "globals": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "Wire names of query/header parameters that become settable once on the generated client and auto-apply to every operation that accepts them; per-call values win. Names that match nothing are reported as generation warnings." }, "include": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "Generate only matching operations: tag names, or path globs such as `/zones/**` (`*` is one path segment, `**` any number), optionally after an HTTP method (`DELETE /zones/*`). Applied before the Spec size limit, with components nothing references any more removed, so a one-shot run can generate part of a Spec up to 64 MB. Selectors that match nothing are reported as generation warnings." }, "exclude": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "Leave out matching operations (tag names or path globs, as for `include`). Wins over `include`." }, "retries": { "$ref": "#/components/schemas/RetryTuning" }, "pagination": { "type": "object", "maxProperties": 100, "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/PaginationRule" }, { "type": "boolean", "description": "false disables pagination detection for the operation." } ] }, "description": "Per-operation pagination control, keyed by operationId or \"METHOD /path\". Unmatched keys are reported as generation warnings." }, "graphql": { "$ref": "#/components/schemas/GraphqlSettings" }, "auth": { "$ref": "#/components/schemas/AuthenticationConfig" }, "cli": { "$ref": "#/components/schemas/CliBehavior" }, "mcp": { "$ref": "#/components/schemas/McpBehavior" }, "readme": { "$ref": "#/components/schemas/ReadmeBehavior" }, "package": { "$ref": "#/components/schemas/PackageBehavior" }, "docs_url": { "type": [ "string", "null" ], "format": "uri", "description": "The API's documentation site. Read through its llms.txt by the generated CLI's docs command, the MCP server's docs tools, and the package's AGENTS.md. Defaults to the Spec's externalDocs URL." }, "docs_index_url": { "type": [ "string", "null" ], "format": "uri", "description": "Exact llms.txt URL when the documentation site does not publish it at docs_url + /llms.txt." } } }, "ProjectConfig": { "type": "object", "additionalProperties": false, "description": "Shared generated-client and tooling behavior for a stored Project. Every Target inherits these defaults. Target.config is merged over them for one Target; top-level values replace defaults while cli, mcp, auth, readme, and package merge by field. GraphQL-only source settings live on the Project's Spec and are rejected in both stored config scopes.", "properties": { "globals": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "Wire names of query/header parameters that become settable once on the generated client and auto-apply to every operation that accepts them; per-call values win. Names that match nothing are reported as generation warnings." }, "include": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "Generate only matching operations: tag names, or path globs such as `/zones/**` (`*` is one path segment, `**` any number), optionally after an HTTP method (`DELETE /zones/*`). Applied before the Spec size limit, with components nothing references any more removed, so a one-shot run can generate part of a Spec up to 64 MB. Selectors that match nothing are reported as generation warnings." }, "exclude": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "Leave out matching operations (tag names or path globs, as for `include`). Wins over `include`." }, "retries": { "$ref": "#/components/schemas/RetryTuning" }, "pagination": { "type": "object", "maxProperties": 100, "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/PaginationRule" }, { "type": "boolean", "description": "false disables pagination detection for the operation." } ] }, "description": "Per-operation pagination control, keyed by operationId or \"METHOD /path\". Unmatched keys are reported as generation warnings." }, "auth": { "$ref": "#/components/schemas/AuthenticationConfig" }, "cli": { "$ref": "#/components/schemas/CliBehavior" }, "mcp": { "$ref": "#/components/schemas/McpBehavior" }, "readme": { "$ref": "#/components/schemas/ReadmeBehavior" }, "package": { "$ref": "#/components/schemas/PackageBehavior" }, "docs_url": { "type": [ "string", "null" ], "format": "uri", "description": "The API's documentation site. Read through its llms.txt by the generated CLI's docs command, the MCP server's docs tools, and the package's AGENTS.md. Defaults to the Spec's externalDocs URL." }, "docs_index_url": { "type": [ "string", "null" ], "format": "uri", "description": "Exact llms.txt URL when the documentation site does not publish it at docs_url + /llms.txt." } } }, "TargetConfig": { "type": "object", "additionalProperties": false, "description": "Target-specific generation and delivery overrides. Authentication may only select a Project-owned OAuth application. OAuth server metadata, applications, and identity policy remain Project-owned. Self-hosted MCP access may be overridden for a Target-specific deployment.", "properties": { "globals": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "Wire names of query/header parameters that become settable once on the generated client and auto-apply to every operation that accepts them; per-call values win. Names that match nothing are reported as generation warnings." }, "include": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "Generate only matching operations: tag names, or path globs such as `/zones/**` (`*` is one path segment, `**` any number), optionally after an HTTP method (`DELETE /zones/*`). Applied before the Spec size limit, with components nothing references any more removed, so a one-shot run can generate part of a Spec up to 64 MB. Selectors that match nothing are reported as generation warnings." }, "exclude": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "Leave out matching operations (tag names or path globs, as for `include`). Wins over `include`." }, "retries": { "$ref": "#/components/schemas/RetryTuning" }, "pagination": { "type": "object", "maxProperties": 100, "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/PaginationRule" }, { "type": "boolean", "description": "false disables pagination detection for the operation." } ] }, "description": "Per-operation pagination control, keyed by operationId or \"METHOD /path\". Unmatched keys are reported as generation warnings." }, "auth": { "$ref": "#/components/schemas/TargetAuthenticationConfig" }, "cli": { "$ref": "#/components/schemas/TargetCliBehavior" }, "mcp": { "$ref": "#/components/schemas/McpBehavior" }, "readme": { "$ref": "#/components/schemas/ReadmeBehavior" }, "package": { "$ref": "#/components/schemas/PackageBehavior" }, "docs_url": { "type": [ "string", "null" ], "format": "uri", "description": "The API's documentation site. Read through its llms.txt by the generated CLI's docs command, the MCP server's docs tools, and the package's AGENTS.md. Defaults to the Spec's externalDocs URL." }, "docs_index_url": { "type": [ "string", "null" ], "format": "uri", "description": "Exact llms.txt URL when the documentation site does not publish it at docs_url + /llms.txt." } } }, "GraphqlSettings": { "type": "object", "additionalProperties": false, "description": "What a GraphQL schema cannot say about itself. Ignored for OpenAPI specs.", "if": { "required": [ "auth" ], "properties": { "auth": { "enum": [ "api_key", "api_key_or_bearer" ] } } }, "then": { "required": [ "api_key_header" ] }, "properties": { "endpoint": { "type": "string", "format": "uri", "description": "The URL every request is POSTed to; the generated client's default baseUrl. Defaults to the URL the schema was fetched from. Without either, baseUrl is a required client option." }, "environments": { "type": "array", "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "url" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "description": "Named endpoints (sandbox, production). Each becomes a client environment; the first is the default unless endpoint is set." }, "auth": { "type": "string", "enum": [ "bearer", "basic", "basic_api_key", "api_key", "api_key_or_bearer", "none" ], "default": "bearer", "description": "How requests authenticate. bearer sends Authorization: Bearer; basic is for key-pair APIs (public key as username, private key as password); basic_api_key sends one API key as the Basic-auth username with an empty password; api_key sends a header named by api_key_header; api_key_or_bearer sends a key in api_key_header (Authorization for a raw key) and also accepts an OAuth access token as Authorization: Bearer; none generates no auth option." }, "api_key_header": { "type": "string", "description": "Header carrying the key when auth is api_key or api_key_or_bearer. Required for those modes; Typeship does not invent a vendor-specific header name." }, "title": { "type": "string", "maxLength": 80, "description": "The API's name; drives the package and client names (\"Acme\" gives acme and AcmeClient). Defaults to a name derived from the endpoint's host." }, "scalars": { "type": "object", "maxProperties": 100, "additionalProperties": { "type": "string", "enum": [ "string", "integer", "number", "boolean", "json" ] }, "description": "JSON representation of each custom scalar, keyed by GraphQL scalar name. Unmapped scalars generate as the language's untyped JSON value and produce a warning. Unmatched keys warn." }, "error_types": { "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^[_A-Za-z][_0-9A-Za-z]*$" }, "description": "Object types that report a failure when an operation's union or interface result resolves to them (errors returned as data). Replaces the default, which is every member whose name ends in Error when the result can also be something else. An empty array treats no result as a failure. Names that are not object types in the schema produce a generation warning." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Page size a paginated connection call sends as first when the caller passes neither first nor last. Relay servers such as GitHub reject a connection query without one. Ignored for a connection whose first argument has a schema default." } } }, "RetryTuning": { "type": "object", "additionalProperties": false, "description": "Retry behavior. Top-level fields adjust every operation; operations maps operationId or \"METHOD /path\" keys to per-operation overrides.", "properties": { "max_retries": { "type": "integer", "minimum": 0, "maximum": 10 }, "statuses": { "type": "array", "items": { "type": "integer" }, "maxItems": 20, "description": "Replaces the default retryable set (408, 429, 500, 502, 503, 504)." }, "initial_delay_ms": { "type": "integer", "minimum": 1 }, "max_delay_ms": { "type": "integer", "minimum": 1 }, "retry_non_idempotent": { "type": "boolean", "description": "Also retry non-idempotent methods (POST/PATCH)." }, "disabled": { "type": "boolean", "description": "Shorthand for max_retries 0." }, "operations": { "type": "object", "maxProperties": 100, "additionalProperties": { "$ref": "#/components/schemas/RetryTuning" } } } }, "PaginationRule": { "type": "object", "additionalProperties": false, "required": [ "items_field" ], "properties": { "style": { "type": "string", "enum": [ "cursor", "cursor_from_last_id", "page", "offset" ], "default": "cursor" }, "items_field": { "type": "string", "description": "Response field holding the item array." }, "cursor_param": { "type": "string" }, "next_cursor_field": { "type": "string" }, "has_more_field": { "type": "string" }, "id_field": { "type": "string" }, "page_param": { "type": "string" }, "offset_param": { "type": "string" }, "limit_param": { "type": "string" } } }, "GenerationStatus": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ], "description": "A Generation moves from queued to running, then completes when its files are saved or fails. Delivery and Draft status are separate." }, "GenerationTrigger": { "type": "string", "enum": [ "manual", "spec_changed", "config_changed", "preview" ] }, "Generation": { "type": "object", "required": [ "id", "object", "project_id", "spec_revision_id", "status", "trigger", "target_id", "type", "name", "version", "warnings", "coverage", "file_count", "errors", "runtime_ms", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/GenerationId" }, "object": { "type": "string", "const": "generation", "readOnly": true }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "spec_revision_id": { "oneOf": [ { "$ref": "#/components/schemas/SpecRevisionId" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/GenerationStatus" }, "trigger": { "$ref": "#/components/schemas/GenerationTrigger" }, "target_id": { "oneOf": [ { "$ref": "#/components/schemas/TargetId" }, { "type": "null" } ] }, "type": { "$ref": "#/components/schemas/GeneratorKind" }, "name": { "type": [ "string", "null" ], "description": "Package name; null until known." }, "version": { "type": [ "string", "null" ], "description": "Package version; null until known." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/GenerationWarning" } }, "coverage": { "oneOf": [ { "$ref": "#/components/schemas/GenerationCoverage" }, { "type": "null" } ], "description": "Operation coverage; null until generation has finished." }, "file_count": { "type": "integer", "minimum": 0, "description": "Generated package files. List them with listGenerationFiles." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/DomainError" } }, "runtime_ms": { "type": [ "integer", "null" ], "minimum": 0, "description": "Milliseconds from the start of the run until it completed or failed; null while queued or running." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "GenerationResponse": { "allOf": [ { "$ref": "#/components/schemas/Generation" }, { "$ref": "#/components/schemas/ResponseMetadata" } ] }, "GenerationBatch": { "type": "object", "description": "One Generation per selected Target. Retrieve each Generation for current status and generated files.", "required": [ "data", "request_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Generation" } }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "ApiKey": { "type": "object", "required": [ "id", "object", "name", "last4", "status", "last_used_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "api_key" }, "name": { "type": "string" }, "last4": { "type": "string", "description": "Last four characters of the secret; the secret itself is never stored." }, "status": { "type": "string", "enum": [ "active", "revoked" ], "description": "active: the key authenticates requests. revoked: it no longer does and cannot be restored; create a new key in the Console or with typeship login." }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the key last changed, such as its revocation." }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "ApiKeyResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "$ref": "#/components/schemas/ResponseMetadata" } ] }, "UrlSpecRevisionSource": { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "const": "url" }, "url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } } } }, "RepositorySpecRevisionSource": { "type": "object", "required": [ "type", "repository" ], "properties": { "type": { "type": "string", "const": "repository" }, "repository": { "type": "object", "required": [ "provider", "identifier", "path" ], "properties": { "provider": { "$ref": "#/components/schemas/RepositoryProvider" }, "identifier": { "$ref": "#/components/schemas/RepositoryIdentifier" }, "path": { "type": "string", "description": "Repository-relative Spec entrypoint path." }, "ref": { "type": [ "string", "null" ], "description": "Git ref resolved for this revision, when recorded." }, "commit_sha": { "type": [ "string", "null" ], "description": "Exact Git commit consumed, when recorded." } } } } }, "SpecRevisionSource": { "oneOf": [ { "$ref": "#/components/schemas/UrlSpecRevisionSource" }, { "$ref": "#/components/schemas/RepositorySpecRevisionSource" } ], "discriminator": { "propertyName": "type", "mapping": { "url": "#/components/schemas/UrlSpecRevisionSource", "repository": "#/components/schemas/RepositorySpecRevisionSource" } } }, "SpecRevision": { "type": "object", "required": [ "id", "object", "project_id", "spec_id", "format", "file_count", "sha256", "size_bytes", "source", "created_at" ], "properties": { "id": { "$ref": "#/components/schemas/SpecRevisionId" }, "object": { "type": "string", "const": "spec_revision" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "spec_id": { "$ref": "#/components/schemas/SpecId" }, "format": { "type": "string", "enum": [ "openapi", "graphql" ] }, "file_count": { "type": "integer", "minimum": 1 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "examples": [ "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" ], "description": "SHA-256 digest of every source file path, digest, and size in the resolved graph." }, "size_bytes": { "type": "integer", "minimum": 0, "description": "Total bytes across all source files." }, "source": { "oneOf": [ { "$ref": "#/components/schemas/SpecRevisionSource" }, { "type": "null" } ], "description": "Origin recorded when this immutable revision was created." }, "diagnostic_summary": { "$ref": "#/components/schemas/DiagnosticSummary", "description": "Present on retrieve; list responses omit it." }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/Diagnostic" }, "description": "Present only with include=diagnostics. Ordered by severity, then rule identifier." }, "patch_diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/DiagnosticWarning" }, "description": "Present only with include=diagnostics. Coded misses or conflicts from applying the Spec's patches to this revision." }, "created_at": { "type": "string", "format": "date-time" }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "SpecRevisionResponse": { "allOf": [ { "$ref": "#/components/schemas/SpecRevision" }, { "$ref": "#/components/schemas/ResponseMetadata" } ], "required": [ "diagnostic_summary" ] }, "ProjectList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor", "request_id" ], "properties": { "object": { "$ref": "#/components/schemas/ListObject" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "has_more": { "type": "boolean", "description": "Whether another page is available after this one." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as cursor to retrieve the next page; null on the last page." }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "GenerationList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor", "request_id" ], "properties": { "object": { "$ref": "#/components/schemas/ListObject" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Generation" } }, "has_more": { "type": "boolean", "description": "Whether another page is available after this one." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as cursor to retrieve the next page; null on the last page." }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "SpecRevisionList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor", "request_id" ], "properties": { "object": { "$ref": "#/components/schemas/ListObject" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SpecRevision" } }, "has_more": { "type": "boolean", "description": "Whether another page is available after this one." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as cursor to retrieve the next page; null on the last page." }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "ApiKeyList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor", "request_id" ], "properties": { "object": { "$ref": "#/components/schemas/ListObject" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "has_more": { "type": "boolean", "description": "Whether another page is available after this one." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as cursor to retrieve the next page; null on the last page." }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "DeletedProject": { "type": "object", "required": [ "id", "object", "deleted", "request_id" ], "properties": { "id": { "$ref": "#/components/schemas/ProjectId" }, "object": { "type": "string", "const": "project" }, "deleted": { "type": "boolean", "const": true }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "DeletedTarget": { "type": "object", "required": [ "id", "object", "deleted", "request_id" ], "properties": { "id": { "$ref": "#/components/schemas/TargetId" }, "object": { "type": "string", "const": "target" }, "deleted": { "type": "boolean", "const": true }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "ErrorType": { "type": "string", "enum": [ "request", "auth", "idempotency", "rate_limit", "organization", "source", "api" ], "description": "Who can resolve the error. request: change the request. auth: fix the credential or its grant. idempotency: change or wait on the Idempotency-Key. rate_limit: wait before retrying. organization: the organization's plan must change. source: a system you own failed, such as the Spec URL, repository, or package registry. api: Typeship failed." }, "ErrorCode": { "type": "string", "enum": [ "input_invalid", "input_missing", "input_type_invalid", "input_format_invalid", "input_too_long", "input_too_short", "input_duplicate", "input_unknown", "query_param_invalid", "cursor_invalid", "method_not_allowed", "resource_not_found", "idempotency_key_invalid", "idempotency_key_reused", "idempotency_key_in_use", "auth_required", "api_key_invalid", "token_invalid", "organization_required", "insufficient_scope", "role_insufficient", "rate_limit_exceeded", "feature_not_available", "quota_exceeded", "spec_invalid", "spec_too_large", "spec_unreachable", "repository_provider_unsupported", "repository_disconnected", "repository_unavailable", "target_busy", "targets_inactive", "no_draft", "draft_merged", "resource_changed", "precondition_failed", "version_invalid", "version_occupied", "version_too_low", "target_already_released", "adoption_unverified", "publication_disabled", "publication_not_retryable", "publication_recovery_unavailable", "publication_failed", "delivery_conflict", "delivery_exists", "resource_has_dependencies", "customization_conflict", "checks_failed", "draft_title_invalid", "history_recovery_required", "checks_unavailable", "regeneration_failed", "follow_up_failed", "api_error" ], "description": "Stable programmatic identifier. Do not branch on message." }, "ErrorDetail": { "type": "object", "required": [ "type", "code", "message", "retryable", "suggested_action", "docs_url" ], "properties": { "type": { "$ref": "#/components/schemas/ErrorType" }, "code": { "$ref": "#/components/schemas/ErrorCode" }, "phase": { "$ref": "#/components/schemas/FailurePhase" }, "target_id": { "$ref": "#/components/schemas/TargetId", "description": "The affected Target when an operation reports failures for multiple Targets." }, "field": { "type": "string", "description": "JSON Pointer to the invalid field within the request part named by in. When in is omitted, the pointer refers to the request body. Header pointers use lowercase header names, such as /idempotency-key." }, "in": { "type": "string", "enum": [ "body", "query", "header" ], "description": "Request part containing field. Query-parameter errors use query; header errors use header. Body errors use body or omit in." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change." }, "retryable": { "type": "boolean", "description": "Whether another attempt can succeed without correcting the inputs. For a recorded failure, start generation or publishing again; retrieving the resource or replaying an idempotency key does not start another attempt." }, "suggested_action": { "type": "string", "description": "Stable, concise recovery instruction suitable for a person or agent." }, "docs_url": { "type": "string", "format": "uri", "description": "Documentation for this class of error." } } }, "RepositoryReferenceResponse": { "type": "object", "required": [ "provider", "identifier" ], "properties": { "provider": { "$ref": "#/components/schemas/RepositoryProvider" }, "identifier": { "$ref": "#/components/schemas/RepositoryIdentifier" } } }, "SpecPatchResponse": { "type": "object", "examples": [ { "op": "remove", "path": "/components/schemas/Legacy" } ], "description": "A fix applied to the resolved Spec before generation. Paths are JSON\nPointers into the document. A patch whose target no longer exists is\nskipped and reported as a warning on the generation, never silently.\n", "required": [ "op", "path" ], "properties": { "op": { "type": "string", "enum": [ "set", "append", "remove", "rename" ] }, "path": { "type": "string", "description": "JSON-Pointer-style path. Pattern segments enable bulk fixes:\n* (any child), ** (any depth), [key=value] (filter), e.g.\n/paths/**/parameters/[name=account_id]/schema/type. Renaming a\nschema under /components/schemas also rewrites its $refs.\n" }, "value": { "description": "set only; the replacement value." }, "to": { "type": [ "string", "null" ], "description": "rename only; the new key name." }, "reason": { "type": [ "string", "null" ] } } }, "DiagnosticSuppressionResponse": { "type": "object", "required": [ "rule_id", "reason" ], "properties": { "rule_id": { "type": "string", "maxLength": 160 }, "path": { "type": "string", "maxLength": 4096, "description": "Exact schema coordinate. Omit only to suppress every occurrence of the rule." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The reviewed product decision behind this exception." } } }, "DiagnosticPolicyResponse": { "type": "object", "description": "Source pull-request enforcement threshold, new-versus-complete baseline, and explicitly reviewed rule or location exceptions.", "required": [ "fail_on", "only_new", "suppressions" ], "properties": { "fail_on": { "type": "string", "enum": [ "never", "error", "warning" ], "default": "error", "description": "Severity threshold that fails the API change review check." }, "only_new": { "type": "boolean", "default": true, "description": "Enforce only occurrences introduced by the proposed source change." }, "suppressions": { "type": "array", "default": [], "maxItems": 100, "items": { "$ref": "#/components/schemas/DiagnosticSuppressionResponse" } } } }, "TargetChecksResponse": { "type": "object", "properties": { "generated": { "type": "array", "uniqueItems": true, "default": [ "build", "package", "public_entrypoint" ], "items": { "type": "string", "enum": [ "build", "package", "public_entrypoint" ] } }, "repository_required": { "type": "array", "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "customer": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "name", "command" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "command": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } }, "description": "Required checks run against the code in the Draft. Generated checks and customer commands share one reproducible workflow; repository_required names existing repository checks. Supplying checks replaces all settings. Omitted generated restores build, package, and public_entrypoint; omitted repository_required and customer restore empty lists. An empty object restores these defaults. An empty array clears the corresponding list." }, "OAuthServerResponse": { "type": "object", "description": "Authorization-server metadata used by generated OAuth flows. Secrets and runtime credentials are never accepted here.", "properties": { "issuer": { "type": [ "string", "null" ], "format": "uri", "description": "Exact authorization-server issuer, including any tenant path." }, "discovery_url": { "type": [ "string", "null" ], "format": "uri", "description": "Exact metadata URL when it cannot be derived from the issuer." }, "authorization_url": { "type": [ "string", "null" ], "format": "uri", "description": "Authorization endpoint override." }, "token_url": { "type": [ "string", "null" ], "format": "uri", "description": "Token endpoint override." }, "device_authorization_url": { "type": [ "string", "null" ], "format": "uri", "description": "Device-authorization endpoint override." }, "scopes": { "type": [ "array", "null" ], "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "^\\S+$" }, "description": "Default scopes requested during login." }, "audience": { "type": [ "string", "null" ], "description": "Default audience included in authorization and token requests." }, "resource": { "type": [ "string", "null" ], "format": "uri", "description": "Protected API resource included in authorization and token requests." } } }, "OAuthApplicationResponse": { "type": "object", "required": [ "client_id" ], "description": "OAuth application available to generated products. Public clients support interactive login; confidential clients support runtime-supplied machine credentials. Client secrets are never stored.", "properties": { "client_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "OAuth client identifier." }, "login_method": { "type": [ "string", "null" ], "enum": [ "browser", "device", null ], "description": "Interactive login method. Browser login uses Authorization Code with PKCE." }, "client_auth_method": { "type": [ "string", "null" ], "enum": [ "post", "basic", null ], "description": "How a runtime-supplied client secret is sent for machine grants." }, "redirect_uri": { "type": [ "string", "null" ], "format": "uri", "description": "Loopback callback URL for browser login." }, "organization_parameter": { "type": [ "string", "null" ], "enum": [ "organization", "organization_id", null ], "description": "Provider parameter used to request an organization during browser login." } } }, "IdentityVerificationResponse": { "description": "Authenticated identity read used to verify a login before it is saved. Operation is auto-detected when omitted or null. At least one of subject_field, account_field, or organization_field must be a non-null JSON Pointer. Null clears an individual mapping while another remains. Set identity_verification itself to null to remove the whole policy.", "example": { "subject_field": "/id", "account_field": "/account_id", "organization_field": "/organization_id" }, "allOf": [ { "type": "object", "properties": { "operation": { "type": [ "string", "null" ], "maxLength": 2000, "pattern": "^[\\w$]+\\.[\\w$]+$", "description": "resource.method of a safe identity read with no required arguments." }, "subject_field": { "type": [ "string", "null" ], "maxLength": 512, "pattern": "^/(?:[^~\\x00-\\x1f\\x7f]|~[01])*$", "description": "JSON Pointer to the stable caller ID in the identity response.", "example": "/id" }, "account_field": { "type": [ "string", "null" ], "maxLength": 512, "pattern": "^/(?:[^~\\x00-\\x1f\\x7f]|~[01])*$", "description": "JSON Pointer to the customer account ID.", "example": "/account_id" }, "organization_field": { "type": [ "string", "null" ], "maxLength": 512, "pattern": "^/(?:[^~\\x00-\\x1f\\x7f]|~[01])*$", "description": "JSON Pointer to the customer organization ID.", "example": "/organization_id" } } }, { "anyOf": [ { "required": [ "subject_field" ], "properties": { "subject_field": { "type": "string" } } }, { "required": [ "account_field" ], "properties": { "account_field": { "type": "string" } } }, { "required": [ "organization_field" ], "properties": { "organization_field": { "type": "string" } } } ] } ] }, "AuthenticationEnvironmentResponse": { "type": "object", "description": "OAuth application and request-value overrides for one named API environment.", "properties": { "oauth_application": { "type": [ "string", "null" ], "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "scopes": { "type": [ "array", "null" ], "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "^\\S+$" } }, "audience": { "type": [ "string", "null" ] }, "resource": { "type": [ "string", "null" ], "format": "uri" } } }, "AuthenticationConfigResponse": { "type": "object", "description": "Public authentication defaults for generated clients and tools. Stored Projects own the OAuth server, application catalog, and identity policy; one-shot generation accepts the same shape for one run. Runtime credentials and client secrets are never accepted.", "properties": { "oauth_server": { "oneOf": [ { "$ref": "#/components/schemas/OAuthServerResponse" }, { "type": "null" } ] }, "oauth_applications": { "type": [ "object", "null" ], "maxProperties": 20, "propertyNames": { "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "additionalProperties": { "$ref": "#/components/schemas/OAuthApplicationResponse" }, "description": "OAuth applications keyed by a stable name." }, "oauth_application": { "type": [ "string", "null" ], "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "description": "Default OAuth application used by generated products." }, "identity_verification": { "oneOf": [ { "$ref": "#/components/schemas/IdentityVerificationResponse" }, { "type": "null" } ] }, "approval_url": { "type": [ "string", "null" ], "format": "uri", "description": "Base URL of a custom browser-approval backend implementing the start, status, and revoke contract. Used only when OAuth is not configured." }, "environments": { "type": [ "object", "null" ], "maxProperties": 20, "propertyNames": { "pattern": "^[A-Za-z_$][A-Za-z0-9_$]{0,127}$" }, "additionalProperties": { "$ref": "#/components/schemas/AuthenticationEnvironmentResponse" }, "description": "Authentication selections keyed by generated API environment name." }, "credential_variables": { "type": [ "object", "null" ], "maxProperties": 20, "propertyNames": { "minLength": 1, "maxLength": 200 }, "additionalProperties": { "oneOf": [ { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]{0,127}$" }, { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]{0,127}$" }, "password": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]{0,127}$" } } } ] }, "description": "Environment variables the generated CLI, MCP server, and SDK environment fallbacks read, keyed by security scheme name. A string names the token or key variable; a Basic scheme takes { username, password }. Wins over the scheme's x-typeship-env extension. Without either, names derive from the package and scheme." }, "credential_parameters": { "type": [ "object", "null" ], "maxProperties": 200, "propertyNames": { "minLength": 1, "maxLength": 500 }, "additionalProperties": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "boolean" } }, "description": "Whether a parameter carries the operation's credential, keyed by operationId, \"METHOD /path\", or \"*\" for every operation, then by the parameter's wire name. true leaves the parameter out of generated signatures, CLI flags, and MCP tool input, because the configured credential already reaches the API; false keeps it. Wins over the parameter's x-typeship-credential extension and the generator's inference." } } }, "TargetAuthenticationEnvironmentResponse": { "type": "object", "properties": { "oauth_application": { "type": [ "string", "null" ], "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$" } } }, "TargetAuthenticationConfigResponse": { "type": "object", "description": "Selects a Project OAuth application for one Target. OAuth server metadata, applications, and identity policy remain Project-owned.", "properties": { "oauth_application": { "type": [ "string", "null" ], "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "description": "Project OAuth application to use. Omit to inherit the Project default." }, "environments": { "type": [ "object", "null" ], "maxProperties": 20, "propertyNames": { "pattern": "^[A-Za-z_$][A-Za-z0-9_$]{0,127}$" }, "additionalProperties": { "$ref": "#/components/schemas/TargetAuthenticationEnvironmentResponse" }, "description": "Project OAuth application selections keyed by API environment." } } }, "CliBehaviorResponse": { "type": "object", "description": "How the generated CLI behaves. Part of Config.", "properties": { "command_name": { "type": [ "string", "null" ], "description": "Command users run, independent of how the CLI is distributed." }, "changelog_url": { "type": [ "string", "null" ], "description": "Public HTTP(S) URL read by the optional changelog command in generated CLIs. Supports UTF-8 Markdown, plain text, and static HTML; embedded credentials are not allowed. Omit or clear to disable, then regenerate." }, "support_url": { "type": [ "string", "null" ], "description": "Where the generated CLI's feedback command sends users. GitHub issues/new URLs get a prefilled title and environment details." }, "mcp_url": { "type": [ "string", "null" ], "description": "Fallback MCP endpoint used by the generated CLI when the Project has no Typeship-hosted MCP endpoint. A hosted endpoint takes precedence over this URL." }, "skills_repo": { "type": [ "string", "null" ], "description": "Repository in owner/name format that the generated CLI's init command offers for skill installation." } } }, "TargetCliBehaviorResponse": { "type": "object", "description": "How the generated CLI behaves. Part of Config.", "properties": { "command_name": { "type": [ "string", "null" ], "description": "Command users run, independent of how the CLI is distributed." }, "changelog_url": { "type": [ "string", "null" ], "description": "Public HTTP(S) URL read by the optional changelog command in generated CLIs. Supports UTF-8 Markdown, plain text, and static HTML; embedded credentials are not allowed. Omit or clear to disable, then regenerate." }, "support_url": { "type": [ "string", "null" ], "description": "Where the generated CLI's feedback command sends users. GitHub issues/new URLs get a prefilled title and environment details." }, "mcp_url": { "type": [ "string", "null" ], "description": "Fallback MCP endpoint used by the generated CLI when the Project has no Typeship-hosted MCP endpoint. A hosted endpoint takes precedence over this URL." }, "skills_repo": { "type": [ "string", "null" ], "description": "Repository in owner/name format that the generated CLI's init command offers for skill installation." }, "relay": { "type": "boolean", "description": "Enable webhook relay sessions for this CLI Target. Requires Pro. Turning it off prevents new sessions." }, "unit_tests": { "type": "boolean", "description": "Also generate unit tests for the helper code a CLI shares, such as raw API path checks, saved credentials, and MCP client configuration. Applies to cli Targets. Off by default; tests for the generated commands are always included." } } }, "McpBehaviorResponse": { "type": "object", "description": "How generated MCP servers and the Typeship-hosted endpoint behave. Part of Config.", "properties": { "registry_name": { "type": [ "string", "null" ], "description": "Stable official MCP registry name, independent of the server runtime." }, "access": { "type": "object", "required": [ "issuer", "resource" ], "description": "Authorization for callers connecting to a generated MCP server deployed over HTTP. The hosting application resolves upstream API credentials separately at runtime. This setting does not apply to the Typeship-hosted endpoint.", "properties": { "issuer": { "type": "string", "format": "uri", "description": "Exact issuer allowed to sign MCP connection tokens." }, "resource": { "type": "string", "format": "uri", "description": "Canonical public URL of the self-hosted MCP endpoint that connection tokens must target." }, "jwks_url": { "type": "string", "format": "uri", "description": "Public signing-key endpoint. Omit to discover it from the issuer." }, "scopes": { "type": "array", "maxItems": 20, "items": { "type": "string" }, "description": "Minimum scopes required to connect to the self-hosted MCP server." } } }, "tool_mode": { "type": "string", "enum": [ "auto", "operations", "meta" ], "description": "MCP tool shape. meta collapses per-operation tools into search_docs, read_docs, and execute so large APIs don't flood an agent's context window. Auto considers the serialized tool schemas, switching near 10k tokens or above 100 operations." }, "instructions": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Guidance appended to the MCP server's instructions, which agents read once when they connect (server/discover): what to call first, conventions the spec does not state, what not to do. Carried by the package's server and the hosted endpoint alike." }, "tool_descriptions": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 600 }, "maxProperties": 200, "description": "Hand-written MCP tool descriptions keyed by operationId or \"METHOD /path\". Each replaces the text typeship derives for that operation (summary, first sentence, method and path, deprecation and auth notes). For flows the spec cannot describe, such as a multi-step upload. Keys that match no operation are reported as generation warnings." }, "reference_resolvers": { "type": "object", "maxProperties": 200, "description": "Exact name-or-ID resolver overrides keyed first by the target operationId or \"METHOD /path\", then by its wire argument name. A resolver names one read collection operation plus 1-4 item fields to match case-insensitively; false opts that argument out of strict inference.", "additionalProperties": { "type": "object", "maxProperties": 20, "additionalProperties": { "oneOf": [ { "type": "boolean", "enum": [ false ] }, { "type": "object", "required": [ "via", "match" ], "properties": { "via": { "type": "string", "maxLength": 200, "description": "OperationId, \"METHOD /path\", MCP tool name, or dotted resource.method of the list operation." }, "match": { "type": "array", "minItems": 1, "maxItems": 4, "uniqueItems": true, "items": { "type": "string", "maxLength": 100 }, "description": "Item fields compared exactly and case-insensitively, such as name, slug, key, or email." }, "id": { "type": "string", "maxLength": 100, "description": "Item field substituted into the requested argument. Defaults to id." } } } ] } } } } }, "ReadmeBehaviorResponse": { "type": "object", "description": "Generated README behavior. Part of Config.", "properties": { "quickstart_operation": { "type": [ "string", "null" ], "maxLength": 500, "description": "operationId or \"METHOD /path\" to feature as the README's first API call. It must be present in the generated package and callable with no required input beyond path placeholders. Missing or unsuitable choices produce a warning and use the automatic example." } } }, "PackageBehaviorResponse": { "type": "object", "description": "Published-package metadata the API spec does not own. Repository is derived from each destination.", "properties": { "title": { "type": [ "string", "null" ], "maxLength": 100, "description": "The API's name as generated READMEs, AGENTS.md, package descriptions, and help text show it, such as \"Parcel\" for a Spec titled \"Parcel - Public API\". Display only: package, client, and command names still come from the Spec. Defaults to the Spec title with common noise removed (\"Parcel - API\" shows as Parcel)." }, "homepage": { "type": [ "string", "null" ], "description": "Homepage written into registry metadata." }, "license": { "type": [ "string", "null" ], "maxLength": 200, "description": "SPDX identifier written into registry metadata. Defaults to info.license." }, "license_text": { "type": [ "string", "null" ], "maxLength": 100000, "description": "Exact LICENSE file contents. Supply this for licences the engine does not build in; MIT is built in when copyright is also set." }, "copyright": { "type": [ "string", "null" ], "maxLength": 200, "description": "Copyright line used in generated license files." }, "go_package_name": { "type": [ "string", "null" ], "description": "Go identifier when the destination repository name is unsuitable." } } }, "ProjectConfigResponse": { "type": "object", "description": "Shared generated-client and tooling behavior for a stored Project. Every Target inherits these defaults. Target.config is merged over them for one Target; top-level values replace defaults while cli, mcp, auth, readme, and package merge by field. GraphQL-only source settings live on the Project's Spec and are rejected in both stored config scopes.", "properties": { "globals": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "Wire names of query/header parameters that become settable once on the generated client and auto-apply to every operation that accepts them; per-call values win. Names that match nothing are reported as generation warnings." }, "include": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "Generate only matching operations: tag names, or path globs such as `/zones/**` (`*` is one path segment, `**` any number), optionally after an HTTP method (`DELETE /zones/*`). Applied before the Spec size limit, with components nothing references any more removed, so a one-shot run can generate part of a Spec up to 64 MB. Selectors that match nothing are reported as generation warnings." }, "exclude": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "Leave out matching operations (tag names or path globs, as for `include`). Wins over `include`." }, "retries": { "$ref": "#/components/schemas/RetryTuningResponse" }, "pagination": { "type": "object", "maxProperties": 100, "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/PaginationRuleResponse" }, { "type": "boolean", "description": "false disables pagination detection for the operation." } ] }, "description": "Per-operation pagination control, keyed by operationId or \"METHOD /path\". Unmatched keys are reported as generation warnings." }, "auth": { "$ref": "#/components/schemas/AuthenticationConfigResponse" }, "cli": { "$ref": "#/components/schemas/CliBehaviorResponse" }, "mcp": { "$ref": "#/components/schemas/McpBehaviorResponse" }, "readme": { "$ref": "#/components/schemas/ReadmeBehaviorResponse" }, "package": { "$ref": "#/components/schemas/PackageBehaviorResponse" }, "docs_url": { "type": [ "string", "null" ], "format": "uri", "description": "The API's documentation site. Read through its llms.txt by the generated CLI's docs command, the MCP server's docs tools, and the package's AGENTS.md. Defaults to the Spec's externalDocs URL." }, "docs_index_url": { "type": [ "string", "null" ], "format": "uri", "description": "Exact llms.txt URL when the documentation site does not publish it at docs_url + /llms.txt." } } }, "TargetConfigResponse": { "type": "object", "description": "Target-specific generation and delivery overrides. Authentication may only select a Project-owned OAuth application. OAuth server metadata, applications, and identity policy remain Project-owned. Self-hosted MCP access may be overridden for a Target-specific deployment.", "properties": { "globals": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "Wire names of query/header parameters that become settable once on the generated client and auto-apply to every operation that accepts them; per-call values win. Names that match nothing are reported as generation warnings." }, "include": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "Generate only matching operations: tag names, or path globs such as `/zones/**` (`*` is one path segment, `**` any number), optionally after an HTTP method (`DELETE /zones/*`). Applied before the Spec size limit, with components nothing references any more removed, so a one-shot run can generate part of a Spec up to 64 MB. Selectors that match nothing are reported as generation warnings." }, "exclude": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "Leave out matching operations (tag names or path globs, as for `include`). Wins over `include`." }, "retries": { "$ref": "#/components/schemas/RetryTuningResponse" }, "pagination": { "type": "object", "maxProperties": 100, "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/PaginationRuleResponse" }, { "type": "boolean", "description": "false disables pagination detection for the operation." } ] }, "description": "Per-operation pagination control, keyed by operationId or \"METHOD /path\". Unmatched keys are reported as generation warnings." }, "auth": { "$ref": "#/components/schemas/TargetAuthenticationConfigResponse" }, "cli": { "$ref": "#/components/schemas/TargetCliBehaviorResponse" }, "mcp": { "$ref": "#/components/schemas/McpBehaviorResponse" }, "readme": { "$ref": "#/components/schemas/ReadmeBehaviorResponse" }, "package": { "$ref": "#/components/schemas/PackageBehaviorResponse" }, "docs_url": { "type": [ "string", "null" ], "format": "uri", "description": "The API's documentation site. Read through its llms.txt by the generated CLI's docs command, the MCP server's docs tools, and the package's AGENTS.md. Defaults to the Spec's externalDocs URL." }, "docs_index_url": { "type": [ "string", "null" ], "format": "uri", "description": "Exact llms.txt URL when the documentation site does not publish it at docs_url + /llms.txt." } } }, "GraphqlSettingsResponse": { "type": "object", "description": "What a GraphQL schema cannot say about itself. Ignored for OpenAPI specs.", "if": { "required": [ "auth" ], "properties": { "auth": { "enum": [ "api_key", "api_key_or_bearer" ] } } }, "then": { "required": [ "api_key_header" ] }, "properties": { "endpoint": { "type": "string", "format": "uri", "description": "The URL every request is POSTed to; the generated client's default baseUrl. Defaults to the URL the schema was fetched from. Without either, baseUrl is a required client option." }, "environments": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "description": "Named endpoints (sandbox, production). Each becomes a client environment; the first is the default unless endpoint is set." }, "auth": { "type": "string", "enum": [ "bearer", "basic", "basic_api_key", "api_key", "api_key_or_bearer", "none" ], "default": "bearer", "description": "How requests authenticate. bearer sends Authorization: Bearer; basic is for key-pair APIs (public key as username, private key as password); basic_api_key sends one API key as the Basic-auth username with an empty password; api_key sends a header named by api_key_header; api_key_or_bearer sends a key in api_key_header (Authorization for a raw key) and also accepts an OAuth access token as Authorization: Bearer; none generates no auth option." }, "api_key_header": { "type": "string", "description": "Header carrying the key when auth is api_key or api_key_or_bearer. Required for those modes; Typeship does not invent a vendor-specific header name." }, "title": { "type": "string", "maxLength": 80, "description": "The API's name; drives the package and client names (\"Acme\" gives acme and AcmeClient). Defaults to a name derived from the endpoint's host." }, "scalars": { "type": "object", "maxProperties": 100, "additionalProperties": { "type": "string", "enum": [ "string", "integer", "number", "boolean", "json" ] }, "description": "JSON representation of each custom scalar, keyed by GraphQL scalar name. Unmapped scalars generate as the language's untyped JSON value and produce a warning. Unmatched keys warn." }, "error_types": { "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^[_A-Za-z][_0-9A-Za-z]*$" }, "description": "Object types that report a failure when an operation's union or interface result resolves to them (errors returned as data). Replaces the default, which is every member whose name ends in Error when the result can also be something else. An empty array treats no result as a failure. Names that are not object types in the schema produce a generation warning." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Page size a paginated connection call sends as first when the caller passes neither first nor last. Relay servers such as GitHub reject a connection query without one. Ignored for a connection whose first argument has a schema default." } } }, "RetryTuningResponse": { "type": "object", "description": "Retry behavior. Top-level fields adjust every operation; operations maps operationId or \"METHOD /path\" keys to per-operation overrides.", "properties": { "max_retries": { "type": "integer", "minimum": 0, "maximum": 10 }, "statuses": { "type": "array", "items": { "type": "integer" }, "maxItems": 20, "description": "Replaces the default retryable set (408, 429, 500, 502, 503, 504)." }, "initial_delay_ms": { "type": "integer", "minimum": 1 }, "max_delay_ms": { "type": "integer", "minimum": 1 }, "retry_non_idempotent": { "type": "boolean", "description": "Also retry non-idempotent methods (POST/PATCH)." }, "disabled": { "type": "boolean", "description": "Shorthand for max_retries 0." }, "operations": { "type": "object", "maxProperties": 100, "additionalProperties": { "$ref": "#/components/schemas/RetryTuningResponse" } } } }, "PaginationRuleResponse": { "type": "object", "required": [ "items_field" ], "properties": { "style": { "type": "string", "enum": [ "cursor", "cursor_from_last_id", "page", "offset" ], "default": "cursor" }, "items_field": { "type": "string", "description": "Response field holding the item array." }, "cursor_param": { "type": "string" }, "next_cursor_field": { "type": "string" }, "has_more_field": { "type": "string" }, "id_field": { "type": "string" }, "page_param": { "type": "string" }, "offset_param": { "type": "string" }, "limit_param": { "type": "string" } } }, "Error": { "type": "object", "required": [ "errors", "request_id" ], "properties": { "errors": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ErrorDetail" } }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "GitFileMode": { "type": "string", "enum": [ "100644", "100755", "120000" ], "description": "Git file mode. 100755 is executable; 120000 is a symbolic link whose content is its target." }, "DraftFileSides": { "type": "object", "required": [ "base", "yours", "generated" ], "description": "File IDs for each side of a conflict or history comparison. null means the file is absent on that side.", "properties": { "base": { "oneOf": [ { "$ref": "#/components/schemas/FileId" }, { "type": "null" } ] }, "yours": { "oneOf": [ { "$ref": "#/components/schemas/FileId" }, { "type": "null" } ] }, "generated": { "oneOf": [ { "$ref": "#/components/schemas/FileId" }, { "type": "null" } ] } } }, "DraftFileConflict": { "type": "object", "required": [ "type", "source", "decision" ], "properties": { "type": { "type": "string", "enum": [ "no_common_version", "file_ownership", "yours_deleted_generated_changed", "generated_deleted_yours_changed", "overlapping_text", "too_large_to_merge", "binary_changed", "file_mode_changed" ], "description": "Why the Draft needs a decision. no_common_version: there is no last merged version to compare, such as the first Draft of an adopted package. file_ownership: generated output collides with a file you added. yours_deleted_generated_changed and generated_deleted_yours_changed: one side deleted a file the other changed. overlapping_text: both sides edited the same lines. too_large_to_merge: the file has too many changed lines to merge line by line. binary_changed and file_mode_changed: both sides changed binary content or the file mode." }, "source": { "type": "string", "enum": [ "generation", "default_branch", "previous_draft" ], "description": "Where the code in this Draft comes from: newly generated files, commits on the default branch, or edits from a Draft whose branch was rebased, reset, or deleted. Typeship may find another conflict after these decisions are applied." }, "decision": { "type": [ "string", "null" ], "enum": [ "yours", "generated", "content", null ], "description": "Decision saved for this conflict on head_sha; null when none. Typeship continues when every conflict has a decision." } } }, "DraftFileHistory": { "type": "object", "required": [ "change", "draft_differs" ], "properties": { "change": { "type": [ "string", "null" ], "enum": [ "added", "edited", "deleted", "mode_changed", null ], "description": "How the rewritten default branch differs from the last merged package; null when only the Draft differs." }, "draft_differs": { "type": "boolean", "description": "The Draft branch has a different version than the rewritten default branch. Recovery carries the Draft version forward." } } }, "DraftFile": { "type": "object", "required": [ "object", "path", "customization", "conflict", "history", "sides" ], "properties": { "object": { "type": "string", "const": "draft_file" }, "path": { "type": "string", "description": "Path relative to the Target's package directory." }, "customization": { "type": [ "string", "null" ], "enum": [ "added", "edited", "deleted", "mode_changed", null ], "description": "How the Draft differs from the last merged package at this path; null when it does not." }, "conflict": { "oneOf": [ { "$ref": "#/components/schemas/DraftFileConflict" }, { "type": "null" } ] }, "history": { "oneOf": [ { "$ref": "#/components/schemas/DraftFileHistory" }, { "type": "null" } ] }, "sides": { "oneOf": [ { "$ref": "#/components/schemas/DraftFileSides" }, { "type": "null" } ], "description": "File IDs to read with getFile for a conflict or history file; null for other customized files." } } }, "DraftFileList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor", "request_id" ], "properties": { "object": { "$ref": "#/components/schemas/ListObject" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DraftFile" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "DraftConflictDecision": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "path", "keep" ], "properties": { "path": { "type": "string", "minLength": 1 }, "keep": { "type": "string", "enum": [ "yours", "generated" ], "description": "Keep that version of the file exactly. Keeping an absent version deletes the path." } } }, { "type": "object", "additionalProperties": false, "required": [ "path", "keep", "content", "mode" ], "properties": { "path": { "type": "string", "minLength": 1 }, "keep": { "type": "string", "const": "content" }, "content": { "type": "string", "description": "Final file text, stored as UTF-8. An empty string creates an empty file." }, "mode": { "$ref": "#/components/schemas/GitFileMode" } } }, { "type": "object", "additionalProperties": false, "required": [ "path", "keep", "content_base64", "mode" ], "properties": { "path": { "type": "string", "minLength": 1 }, "keep": { "type": "string", "const": "content" }, "content_base64": { "type": "string", "description": "Final file bytes as canonical base64, for binary files." }, "mode": { "$ref": "#/components/schemas/GitFileMode" } } }, { "type": "object", "additionalProperties": false, "required": [ "path", "keep", "content" ], "properties": { "path": { "type": "string", "minLength": 1 }, "keep": { "type": "string", "const": "content" }, "content": { "type": "null", "description": "Delete this file." } } } ] }, "DraftResolveRequest": { "type": "object", "additionalProperties": false, "required": [ "expected_head_sha", "resolutions" ], "properties": { "expected_head_sha": { "type": "string", "pattern": "^[0-9a-fA-F]{40}$", "description": "The Draft's head_sha. A newer Draft commit returns 409 resource_changed without saving.", "examples": [ "0123456789abcdef0123456789abcdef01234567" ] }, "resolutions": { "type": "array", "minItems": 1, "maxItems": 1000, "description": "Unique current conflict or customized paths. Choose generated to discard a customization, including a Draft-only file. Final file content must total at most 2 MiB. Decisions apply together or not at all.", "items": { "$ref": "#/components/schemas/DraftConflictDecision" } } } }, "GenerateProjectRequest": { "type": "object", "additionalProperties": false, "properties": { "target_id": { "$ref": "#/components/schemas/TargetId", "description": "Generate only this active Target. Omit to generate all active Targets in the Project." } } }, "FailurePhase": { "type": "string", "enum": [ "spec", "generation", "delivery", "publication" ], "description": "The stage that failed. A delivery failure does not change a completed Generation's status." }, "DomainError": { "allOf": [ { "$ref": "#/components/schemas/ErrorDetail" }, { "type": "object", "required": [ "phase" ], "properties": { "phase": { "$ref": "#/components/schemas/FailurePhase" } } } ] }, "DraftRecoverRequest": { "type": "object", "additionalProperties": false, "required": [ "expected_default_sha", "expected_head_sha" ], "properties": { "expected_default_sha": { "type": "string", "pattern": "^[a-fA-F0-9]{40}$", "description": "The Draft's history_recovery.default_sha." }, "expected_head_sha": { "type": [ "string", "null" ], "pattern": "^[a-fA-F0-9]{40}$", "description": "The Draft's history_recovery.head_sha; null when the Draft branch is absent." } } } }, "parameters": { "IfMatch": { "name": "If-Match", "in": "header", "required": false, "description": "ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes.", "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write.", "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[!-~]+$" } }, "PageLimit": { "name": "limit", "in": "query", "description": "Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "PageCursor": { "name": "cursor", "in": "query", "description": "Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^[A-Za-z0-9_-]+$" } }, "ProjectId": { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProjectId" } }, "GenerationId": { "name": "generation_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/GenerationId" } }, "SpecId": { "name": "spec_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SpecId" } }, "SpecRevisionId": { "name": "spec_revision_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SpecRevisionId" } }, "DeliveryId": { "name": "delivery_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DeliveryId" } }, "TargetId": { "name": "target_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TargetId" } }, "DraftId": { "name": "draft_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DraftId" } }, "ReleaseId": { "name": "release_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ReleaseId" } }, "ApiKeyId": { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Identifier returned by the API key list." }, "example": "apikey_2nY8mR6pQ4vK9cH3" } }, "headers": { "ETag": { "description": "Opaque version of the resource. Send it in If-Match to update only that version.", "schema": { "type": "string" } }, "IdempotencyReplayed": { "description": "Whether this is a replay of the original response for the supplied Idempotency-Key.", "schema": { "type": "boolean" } }, "RequestId": { "description": "Server-generated identifier used to correlate this response with Typeship logs.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "RateLimitLimit": { "description": "Maximum requests in the evaluated rate-limit window. Omitted when no budget was evaluated, including idempotency replays.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimitRemaining": { "description": "Requests remaining immediately after this request evaluated its budget. Concurrent requests can consume this allowance. Omitted when no budget was evaluated.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimitReset": { "description": "Seconds until the evaluated rate-limit window resets, measured when the response is sent. Zero means that window has ended. Omitted when no budget was evaluated.", "schema": { "type": "integer", "minimum": 0 } }, "RetryAfter": { "description": "Seconds to wait before retrying the request.", "schema": { "type": "integer", "minimum": 1 } } }, "responses": { "PreconditionFailed": { "description": "The resource changed since the ETag supplied in If-Match. No write was applied.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PreconditionFailed": { "$ref": "#/components/examples/PreconditionFailed" } } } } }, "BadGateway": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Dependent work failed while completing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "An unexpected error prevented the request from completing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Invalid request.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unprocessable": { "description": "The Spec could not be resolved or analyzed.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SpecInvalid": { "$ref": "#/components/examples/SpecInvalid" } } } } }, "Unauthorized": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Missing, invalid, expired, or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The credentials are valid but cannot act on the requested organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such resource in this organization.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests, or an identical write is still in progress. Wait for Retry-After before retrying.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RateLimitError": { "$ref": "#/components/examples/RateLimitError" } } } } } }, "examples": { "Project": { "summary": "Parcel Project", "value": { "id": "prj_4f8k2m7x9q1v6b3n", "object": "project", "name": "Parcel API", "spec_id": "spec_2p8m4q7k1v9d6h3c", "auto_generate": true, "config": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "UpdatedProject": { "summary": "Updated generation settings", "value": { "id": "prj_4f8k2m7x9q1v6b3n", "object": "project", "name": "Parcel API", "spec_id": "spec_2p8m4q7k1v9d6h3c", "auto_generate": true, "config": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "ProjectList": { "summary": "Last page of Projects", "value": { "object": "list", "data": [ { "id": "prj_4f8k2m7x9q1v6b3n", "object": "project", "name": "Parcel API", "spec_id": "spec_2p8m4q7k1v9d6h3c", "auto_generate": true, "config": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "MoreProjects": { "summary": "Another page of Projects is available", "description": "Pass the exact next_cursor returned by your response to the next list request. This cursor is illustrative.", "value": { "object": "list", "data": [ { "id": "prj_4f8k2m7x9q1v6b3n", "object": "project", "name": "Parcel API", "spec_id": "spec_2p8m4q7k1v9d6h3c", "auto_generate": true, "config": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z" } ], "has_more": true, "next_cursor": "eyJ2IjoxLCJpZCI6InByal80ZjhrMm03eDlxMXY2YjNuIn0", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "DeletedProject": { "summary": "Deleted Project", "value": { "id": "prj_4f8k2m7x9q1v6b3n", "object": "project", "deleted": true, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "Spec": { "summary": "URL Spec", "value": { "id": "spec_2p8m4q7k1v9d6h3c", "object": "spec", "project_id": "prj_4f8k2m7x9q1v6b3n", "source": { "type": "url", "url": { "url": "https://api.parcel.example/openapi.json", "headers_configured": false } }, "format": "openapi", "patches": [], "graphql": null, "diagnostic_policy": { "fail_on": "error", "only_new": false, "suppressions": [] }, "revision_latest_id": "srev_6m1q8v4k2p9d7h3c", "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "RepositorySpec": { "summary": "Repository Spec", "value": { "id": "spec_2p8m4q7k1v9d6h3c", "object": "spec", "project_id": "prj_4f8k2m7x9q1v6b3n", "source": { "type": "repository", "repository": { "provider": "github", "identifier": "parcel-example/api", "path": "openapi.yaml" } }, "format": "openapi", "patches": [], "graphql": null, "diagnostic_policy": { "fail_on": "error", "only_new": false, "suppressions": [] }, "revision_latest_id": "srev_6m1q8v4k2p9d7h3c", "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "Target": { "summary": "Parcel CLI Target", "value": { "id": "tgt_5m8q2v7k1p9d4h6c", "object": "target", "project_id": "prj_4f8k2m7x9q1v6b3n", "spec_id": "spec_2p8m4q7k1v9d6h3c", "name": "Parcel CLI", "type": "cli", "status": "active", "release_channel": "stable", "version_current": "1.0.0", "draft_id": "drf_3q7m1v8k2p5d9h4c", "checks": { "generated": [ "build", "package", "public_entrypoint" ], "repository_required": [], "customer": [] }, "config": { "cli": { "command_name": "parcel" } }, "deliveries": [ { "id": "dlv_4q8m2v7k1p9d5h6c", "object": "delivery", "target_id": "tgt_5m8q2v7k1p9d4h6c", "type": "repository", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client", "directory": null, "package_name": null, "module_path": "github.com/parcel-example/parcel-client", "publish_on_merge": false }, "status": "active", "issues": [], "required_checks": [ "Typeship Release" ], "last_event": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z" } ], "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "DeliveryList": { "summary": "Last page of a Target's Deliveries", "value": { "object": "list", "data": [ { "id": "dlv_4q8m2v7k1p9d5h6c", "object": "delivery", "target_id": "tgt_5m8q2v7k1p9d4h6c", "type": "repository", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client", "directory": null, "package_name": null, "module_path": "github.com/parcel-example/parcel-client", "publish_on_merge": false }, "status": "active", "issues": [], "required_checks": [ "Typeship Release" ], "last_event": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "Delivery": { "summary": "Parcel CLI repository Delivery", "value": { "id": "dlv_4q8m2v7k1p9d5h6c", "object": "delivery", "target_id": "tgt_5m8q2v7k1p9d4h6c", "type": "repository", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client", "directory": null, "package_name": null, "module_path": "github.com/parcel-example/parcel-client", "publish_on_merge": false }, "status": "active", "issues": [], "required_checks": [ "Typeship Release" ], "last_event": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "DeletedDelivery": { "summary": "Deleted Delivery", "value": { "id": "dlv_4q8m2v7k1p9d5h6c", "object": "delivery", "deleted": true, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "CreatedTarget": { "summary": "New Parcel CLI Target", "value": { "id": "tgt_5m8q2v7k1p9d4h6c", "object": "target", "project_id": "prj_4f8k2m7x9q1v6b3n", "spec_id": "spec_2p8m4q7k1v9d6h3c", "name": "Parcel CLI", "type": "cli", "status": "active", "release_channel": "stable", "version_current": null, "draft_id": "drf_3q7m1v8k2p5d9h4c", "checks": { "generated": [ "build", "package", "public_entrypoint" ], "repository_required": [], "customer": [] }, "config": { "cli": { "command_name": "parcel" } }, "deliveries": [ { "id": "dlv_4q8m2v7k1p9d5h6c", "object": "delivery", "target_id": "tgt_5m8q2v7k1p9d4h6c", "type": "repository", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client", "directory": null, "package_name": null, "module_path": "github.com/parcel-example/parcel-client", "publish_on_merge": false }, "status": "active", "issues": [], "required_checks": [ "Typeship Release" ], "last_event": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z" } ], "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "UpdatedTarget": { "summary": "Disabled Target", "value": { "id": "tgt_5m8q2v7k1p9d4h6c", "object": "target", "project_id": "prj_4f8k2m7x9q1v6b3n", "spec_id": "spec_2p8m4q7k1v9d6h3c", "name": "Parcel CLI", "type": "cli", "status": "disabled", "release_channel": "stable", "version_current": "1.0.0", "draft_id": "drf_3q7m1v8k2p5d9h4c", "checks": { "generated": [ "build", "package", "public_entrypoint" ], "repository_required": [], "customer": [] }, "config": { "cli": { "command_name": "parcel" } }, "deliveries": [ { "id": "dlv_4q8m2v7k1p9d5h6c", "object": "delivery", "target_id": "tgt_5m8q2v7k1p9d4h6c", "type": "repository", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client", "directory": null, "package_name": null, "module_path": "github.com/parcel-example/parcel-client", "publish_on_merge": false }, "status": "active", "issues": [], "required_checks": [ "Typeship Release" ], "last_event": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z" } ], "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "TargetList": { "summary": "Last page of Targets", "value": { "object": "list", "data": [ { "id": "tgt_5m8q2v7k1p9d4h6c", "object": "target", "project_id": "prj_4f8k2m7x9q1v6b3n", "spec_id": "spec_2p8m4q7k1v9d6h3c", "name": "Parcel CLI", "type": "cli", "status": "active", "release_channel": "stable", "version_current": "1.0.0", "draft_id": "drf_3q7m1v8k2p5d9h4c", "checks": { "generated": [ "build", "package", "public_entrypoint" ], "repository_required": [], "customer": [] }, "config": { "cli": { "command_name": "parcel" } }, "deliveries": [ { "id": "dlv_4q8m2v7k1p9d5h6c", "object": "delivery", "target_id": "tgt_5m8q2v7k1p9d4h6c", "type": "repository", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client", "directory": null, "package_name": null, "module_path": "github.com/parcel-example/parcel-client", "publish_on_merge": false }, "status": "active", "issues": [], "required_checks": [ "Typeship Release" ], "last_event": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z" } ], "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "DeletedTarget": { "summary": "Deleted Target", "value": { "id": "tgt_5m8q2v7k1p9d4h6c", "object": "target", "deleted": true, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "Release": { "summary": "Accepted release", "value": { "id": "rel_7m2q8v4k1p9d5h6c", "object": "release", "target_id": "tgt_5m8q2v7k1p9d4h6c", "generation_id": "gen_7h2p5d9c3m8w1k6q", "version": "1.0.0", "release_channel": "stable", "origin": "typeship", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client" }, "spec_revision_id": "srev_6m1q8v4k2p9d7h3c", "commit_sha": "0123456789abcdef0123456789abcdef01234567", "checks": [], "approvals": [], "import_provenance": null, "publications": [], "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "RetriedRelease": { "summary": "A release whose npm publishing was retried", "value": { "id": "rel_7m2q8v4k1p9d5h6c", "object": "release", "target_id": "tgt_5m8q2v7k1p9d4h6c", "generation_id": "gen_7h2p5d9c3m8w1k6q", "version": "1.0.0", "release_channel": "stable", "origin": "typeship", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client" }, "spec_revision_id": "srev_6m1q8v4k2p9d7h3c", "commit_sha": "0123456789abcdef0123456789abcdef01234567", "checks": [], "approvals": [], "import_provenance": null, "publications": [ { "type": "github", "status": "completed", "attempt": 1, "run_url": "https://github.com/parcel-example/parcel-client/actions/runs/1001", "registry_url": "https://github.com/parcel-example/parcel-client/releases/tag/v1.0.0", "artifact_digest": null, "errors": [], "started_at": "2026-09-23T08:01:00Z", "finished_at": "2026-09-23T08:02:00Z", "runtime_ms": 60000, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:02:00Z" }, { "type": "npm", "status": "queued", "attempt": 1, "run_url": null, "registry_url": null, "artifact_digest": null, "errors": [], "started_at": null, "finished_at": null, "runtime_ms": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T09:15:00Z" } ], "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T09:15:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "AdoptedRelease": { "summary": "Adopted package version", "value": { "id": "rel_7m2q8v4k1p9d5h6c", "object": "release", "target_id": "tgt_5m8q2v7k1p9d4h6c", "generation_id": null, "version": "1.0.0", "release_channel": "stable", "origin": "imported", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client" }, "spec_revision_id": null, "commit_sha": "0123456789abcdef0123456789abcdef01234567", "checks": [], "approvals": [], "import_provenance": { "tag": "v1.0.0", "registry_url": "https://www.npmjs.com/package/parcel-client/v/1.0.0", "artifact_digest": "sha256:3ccd2685803ba4c4db9bed78c3ef8d1993e119abbdafa1ab5dfa6d31846da05d", "imported_at": "2026-09-23T08:00:00Z" }, "publications": [], "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "ReleaseList": { "summary": "Last page of releases", "value": { "object": "list", "data": [ { "id": "rel_7m2q8v4k1p9d5h6c", "object": "release", "target_id": "tgt_5m8q2v7k1p9d4h6c", "generation_id": "gen_7h2p5d9c3m8w1k6q", "version": "1.0.0", "release_channel": "stable", "origin": "typeship", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client" }, "spec_revision_id": "srev_6m1q8v4k2p9d7h3c", "commit_sha": "0123456789abcdef0123456789abcdef01234567", "checks": [], "approvals": [], "import_provenance": null, "publications": [], "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "Draft": { "summary": "A Draft ready to merge", "value": { "id": "drf_3q7m1v8k2p5d9h4c", "object": "draft", "target_id": "tgt_5m8q2v7k1p9d4h6c", "project_id": "prj_4k8m2v7q1p9d5h6c", "status": "ready", "version_next": "1.1.0", "version_source": "automatic", "compatibility": { "api": "compatible", "package": "compatible" }, "version": { "bump_required": "minor", "correct": true, "previous": "1.0.0" }, "errors": [], "changes": { "changelog": "Add shipment tracking.", "breaking_count": 0 }, "head_sha": "0123456789abcdef0123456789abcdef01234567", "pull_request": { "url": "https://github.com/parcel-example/parcel-client/pull/12", "number": 12 }, "generation_id": "gen_7h2p5d9c3m8w1k6q", "conflicts": null, "customized_files": 2, "release_id": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:30:00Z", "history_recovery": null, "request_id": "req_3k8m1v6q9p2d7h4c", "checks": [] } }, "UpdatedDraft": { "summary": "Explicit Draft version", "value": { "id": "drf_3q7m1v8k2p5d9h4c", "object": "draft", "target_id": "tgt_5m8q2v7k1p9d4h6c", "project_id": "prj_4k8m2v7q1p9d5h6c", "status": "working", "version_next": "1.1.0", "version_source": "api", "compatibility": { "api": "compatible", "package": "compatible" }, "version": { "bump_required": "minor", "correct": null, "previous": "1.0.0" }, "errors": [], "changes": { "changelog": "Add shipment tracking.", "breaking_count": 0 }, "head_sha": "0123456789abcdef0123456789abcdef01234567", "pull_request": { "url": "https://github.com/parcel-example/parcel-client/pull/12", "number": 12 }, "generation_id": "gen_7h2p5d9c3m8w1k6q", "conflicts": null, "customized_files": 2, "release_id": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:30:00Z", "history_recovery": null, "request_id": "req_3k8m1v6q9p2d7h4c", "checks": [] } }, "Generation": { "summary": "Generation with a generated file", "value": { "id": "gen_7h2p5d9c3m8w1k6q", "object": "generation", "project_id": "prj_4f8k2m7x9q1v6b3n", "spec_revision_id": "srev_6m1q8v4k2p9d7h3c", "status": "completed", "trigger": "manual", "target_id": "tgt_5m8q2v7k1p9d4h6c", "type": "cli", "name": "parcel-cli", "version": "1.0.0", "warnings": [], "coverage": { "generated": 12, "omitted": 0, "total": 12, "omitted_operations": [] }, "file_count": 1, "errors": [], "runtime_ms": 4200, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "GenerationBatch": { "summary": "Queued Project Generations", "value": { "data": [ { "id": "gen_7h2p5d9c3m8w1k6q", "object": "generation", "project_id": "prj_4f8k2m7x9q1v6b3n", "spec_revision_id": null, "status": "queued", "trigger": "manual", "target_id": "tgt_5m8q2v7k1p9d4h6c", "type": "cli", "name": null, "version": null, "warnings": [], "coverage": null, "file_count": 0, "errors": [], "runtime_ms": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z" } ], "request_id": "req_3k8m1v6q9p2d7h4c" } }, "GenerationList": { "summary": "Last page of Generations", "value": { "object": "list", "data": [ { "id": "gen_7h2p5d9c3m8w1k6q", "object": "generation", "project_id": "prj_4f8k2m7x9q1v6b3n", "spec_revision_id": "srev_6m1q8v4k2p9d7h3c", "status": "completed", "trigger": "manual", "target_id": "tgt_5m8q2v7k1p9d4h6c", "type": "cli", "name": "parcel-cli", "version": "1.0.0", "warnings": [], "coverage": { "generated": 12, "omitted": 0, "total": 12, "omitted_operations": [] }, "file_count": 1, "errors": [], "runtime_ms": 4200, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "GenerationResult": { "summary": "One-shot Parcel output", "value": { "object": "package", "files": [ { "path": "README.md", "content": "# Parcel CLI\n\nA command-line client for the fictional Parcel API.\n" } ], "warnings": [], "coverage": { "generated": 12, "omitted": 0, "total": 12, "omitted_operations": [] }, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "HostedSampleResult": { "summary": "Hosted Petstore sample output", "value": { "object": "package", "files": [ { "path": "README.md", "content": "# petstore-cli\n\nCLI for Petstore. [API reference](./api.md)\n" } ], "warnings": [], "coverage": { "generated": 20, "omitted": 0, "total": 20, "omitted_operations": [] }, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "SpecRevision": { "summary": "Captured Spec Revision", "value": { "id": "srev_6m1q8v4k2p9d7h3c", "object": "spec_revision", "project_id": "prj_4f8k2m7x9q1v6b3n", "spec_id": "spec_2p8m4q7k1v9d6h3c", "format": "openapi", "file_count": 1, "sha256": "3ccd2685803ba4c4db9bed78c3ef8d1993e119abbdafa1ab5dfa6d31846da05d", "size_bytes": 524, "source": { "type": "url", "url": { "url": "https://api.parcel.example/openapi.json" } }, "diagnostic_summary": { "status": "passed", "error_count": 0, "warning_count": 0, "suggestion_count": 1, "blocking_count": 0, "baseline_spec_revision_id": null }, "created_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "SpecRevisionList": { "summary": "Last page of Spec Revisions", "value": { "object": "list", "data": [ { "id": "srev_6m1q8v4k2p9d7h3c", "object": "spec_revision", "project_id": "prj_4f8k2m7x9q1v6b3n", "spec_id": "spec_2p8m4q7k1v9d6h3c", "format": "openapi", "file_count": 1, "files": [ { "path": "/openapi.json", "role": "entrypoint", "sha256": "3ccd2685803ba4c4db9bed78c3ef8d1993e119abbdafa1ab5dfa6d31846da05d", "size_bytes": 524 } ], "sha256": "3ccd2685803ba4c4db9bed78c3ef8d1993e119abbdafa1ab5dfa6d31846da05d", "size_bytes": 524, "source": { "type": "url", "url": { "url": "https://api.parcel.example/openapi.json" } }, "created_at": "2026-09-23T08:00:00Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "Organization": { "summary": "Parcel organization", "value": { "id": "org_2nY8mR6pQ4vK9cH3", "object": "organization", "name": "Parcel", "plan": "pro", "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "ApiKeyList": { "summary": "Last page of API keys", "value": { "object": "list", "data": [ { "id": "apikey_2nY8mR6pQ4vK9cH3", "object": "api_key", "name": "Parcel deployment", "last4": "c0de", "status": "active", "last_used_at": "2026-09-23T08:00:00Z", "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "ApiKey": { "summary": "Active API key", "value": { "id": "apikey_2nY8mR6pQ4vK9cH3", "object": "api_key", "name": "Parcel deployment", "last4": "c0de", "status": "active", "last_used_at": "2026-09-23T08:00:00Z", "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "RevokedApiKey": { "summary": "Revoked API key", "value": { "id": "apikey_2nY8mR6pQ4vK9cH3", "object": "api_key", "name": "Parcel deployment", "last4": "c0de", "status": "revoked", "last_used_at": "2026-09-23T08:00:00Z", "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "SpecRevisionWithDiagnostics": { "summary": "Spec Revision with its Diagnostics included", "value": { "id": "srev_6m1q8v4k2p9d7h3c", "object": "spec_revision", "project_id": "prj_4f8k2m7x9q1v6b3n", "spec_id": "spec_2p8m4q7k1v9d6h3c", "format": "openapi", "file_count": 1, "sha256": "3ccd2685803ba4c4db9bed78c3ef8d1993e119abbdafa1ab5dfa6d31846da05d", "size_bytes": 524, "source": { "type": "url", "url": { "url": "https://api.parcel.example/openapi.json" } }, "diagnostic_summary": { "status": "passed", "error_count": 0, "warning_count": 0, "suggestion_count": 1, "blocking_count": 0, "baseline_spec_revision_id": null }, "diagnostics": [ { "id": "openapi.info.description.missing", "object": "diagnostic", "severity": "suggestion", "category": "agent_usability", "title": "The API has no top-level description", "message": "Humans and agents otherwise begin with operation names but no model of what the API is for.", "surfaces": [ "api", "sdk", "cli", "mcp" ], "owner_decision_required": true, "blocking": false, "introduced": true, "locations": [ { "file_path": "/openapi.json", "path": "/info", "blocking": false, "introduced": true, "suppressed": false } ], "authoring_brief": "Add a short statement of the Parcel API purpose, audience, and important behavioral constraints to info.description." } ], "patch_diagnostics": [], "created_at": "2026-09-23T08:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "ValidationError": { "summary": "name can't be empty.", "value": { "errors": [ { "type": "request", "code": "input_too_short", "message": "name can't be empty.", "retryable": false, "suggested_action": "Lengthen the value at field to the minimum the operation schema requires, then retry.", "docs_url": "https://typeship.dev/docs/typeship-api/errors#input_too_short", "field": "/name" } ], "request_id": "req_3k8m1v6q9p2d7h4c" } }, "QueryValidationError": { "summary": "limit must be an integer from 1 to 100.", "value": { "errors": [ { "type": "request", "code": "input_invalid", "message": "limit must be an integer from 1 to 100.", "retryable": false, "suggested_action": "Correct the value at field using the operation schema, then retry.", "docs_url": "https://typeship.dev/docs/typeship-api/errors#input_invalid", "field": "/limit", "in": "query" } ], "request_id": "req_3k8m1v6q9p2d7h4c" } }, "PlanError": { "summary": "Your plan does not include another active Project.", "value": { "errors": [ { "type": "organization", "code": "quota_exceeded", "message": "Your plan does not include another active Project.", "retryable": false, "suggested_action": "Upgrade the organization's plan, or disable or delete an existing resource to free capacity, then retry.", "docs_url": "https://typeship.dev/docs/typeship-api/errors#quota_exceeded" } ], "request_id": "req_3k8m1v6q9p2d7h4c" } }, "IdempotencyConflict": { "summary": "This Idempotency-Key was already used for a different request.", "value": { "errors": [ { "type": "idempotency", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used for a different request.", "retryable": false, "suggested_action": "Use the original request parameters or send a new Idempotency-Key.", "docs_url": "https://typeship.dev/docs/typeship-api/errors#idempotency_key_reused" } ], "request_id": "req_3k8m1v6q9p2d7h4c" } }, "PreconditionFailed": { "summary": "The Draft changed since you last read it.", "value": { "errors": [ { "type": "request", "code": "precondition_failed", "field": "/if-match", "in": "header", "message": "The Draft changed since you last read it. Get it again, reconcile your change, and retry with its current ETag.", "retryable": false, "suggested_action": "Get the resource again, reconcile your change with its current state, then repeat the request with its new ETag in If-Match.", "docs_url": "https://typeship.dev/docs/typeship-api/errors#precondition_failed" } ], "request_id": "req_3k8m1v6q9p2d7h4c" } }, "SpecInvalid": { "summary": "The Spec must include an OpenAPI version.", "value": { "errors": [ { "type": "request", "code": "spec_invalid", "message": "The Spec must include an OpenAPI version.", "retryable": false, "suggested_action": "Fix the source Spec using the reported error, then run generation again.", "docs_url": "https://typeship.dev/docs/typeship-api/errors#spec_invalid" } ], "request_id": "req_3k8m1v6q9p2d7h4c" } }, "RateLimitError": { "summary": "Too many requests.", "value": { "errors": [ { "type": "rate_limit", "code": "rate_limit_exceeded", "message": "Too many requests.", "retryable": true, "suggested_action": "Wait for the Retry-After interval before retrying.", "docs_url": "https://typeship.dev/docs/typeship-api/errors#rate_limit_exceeded" } ], "request_id": "req_3k8m1v6q9p2d7h4c" } }, "DraftFileList": { "summary": "A conflict with its readable versions, and a preserved helper", "value": { "object": "list", "data": [ { "object": "draft_file", "path": "src/helper.ts", "customization": "added", "conflict": null, "history": null, "sides": null }, { "object": "draft_file", "path": "src/index.ts", "customization": "edited", "conflict": { "type": "overlapping_text", "source": "generation", "decision": null }, "history": null, "sides": { "base": "file_2q7m1v8k4p9d5h3c", "yours": "file_8w3k6q2m9v1p4d7h", "generated": "file_4k8m2v7q1p9d5h6c" } } ], "has_more": false, "next_cursor": null, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "File": { "summary": "The generated side of a conflicted file", "value": { "id": "file_4k8m2v7q1p9d5h6c", "object": "file", "path": "src/index.ts", "size_bytes": 94, "sha256": "5f1d7c0a4b8e2f6a9c3d7e1b5a9f2c6d0e4b8a3f7c1d5e9b2a6f0c4d8e2b6a1f", "encoding": "utf8", "mode": "100644", "created_at": "2026-09-23T08:40:00Z", "content": "export { ParcelClient } from \"./client.js\";\nexport type { Shipment, Label } from \"./types.js\";\n", "offset": 0, "next_cursor": null, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "GenerationFileList": { "summary": "Files in a generated package", "value": { "object": "list", "data": [ { "id": "file_7n3q9v2k5m8d1h4c", "object": "file", "path": "README.md", "size_bytes": 66, "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae", "encoding": "utf8", "mode": "100644", "created_at": "2026-09-23T08:05:00Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "SpecRevisionFileList": { "summary": "A Spec Revision's source file and resolved document", "value": { "object": "list", "data": [ { "id": "file_9d4k7m2q6v1p8h3c", "object": "file", "path": "/openapi.json", "role": "entrypoint", "size_bytes": 524, "sha256": "3ccd2685803ba4c4db9bed78c3ef8d1993e119abbdafa1ab5dfa6d31846da05d", "encoding": "utf8", "mode": null, "created_at": "2026-09-23T08:00:00Z" }, { "id": "file_1h6q3v9k2m7d4p8c", "object": "file", "path": "openapi.normalized.json", "role": "resolved", "size_bytes": 611, "sha256": "8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4", "encoding": "utf8", "mode": null, "created_at": "2026-09-23T08:00:00Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_3k8m1v6q9p2d7h4c" } }, "ResolvedDraft": { "summary": "Last conflict decided; Typeship continues the Draft", "value": { "id": "drf_3q7m1v8k2p5d9h4c", "object": "draft", "target_id": "tgt_5m8q2v7k1p9d4h6c", "project_id": "prj_4k8m2v7q1p9d5h6c", "status": "working", "version_next": "1.1.0", "version_source": "automatic", "compatibility": null, "version": null, "errors": [], "checks": [], "changes": { "changelog": "Add shipment tracking.", "breaking_count": 0 }, "head_sha": "0123456789abcdef0123456789abcdef01234567", "pull_request": { "url": "https://github.com/parcel-example/parcel-client/pull/12", "number": 12 }, "generation_id": "gen_7h2p5d9c3m8w1k6q", "release_id": null, "conflicts": { "total": 1, "decided": 1 }, "customized_files": 2, "history_recovery": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:45:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "BlockedDraft": { "summary": "A Draft blocked by a failed required check", "value": { "id": "drf_3q7m1v8k2p5d9h4c", "object": "draft", "target_id": "tgt_5m8q2v7k1p9d4h6c", "project_id": "prj_4k8m2v7q1p9d5h6c", "status": "action_required", "reason": "checks_failed", "version_next": "1.1.0", "version_source": "automatic", "compatibility": { "api": "compatible", "package": "compatible" }, "version": { "bump_required": "minor", "correct": true, "previous": "1.0.0" }, "errors": [ { "type": "request", "code": "checks_failed", "message": "Required check \"npm test\" failed: 2 tests failed in tracking.test.ts.", "retryable": false, "suggested_action": "Open the failed check's url, fix the package or check in the Draft pull request, then push to rerun it.", "docs_url": "https://typeship.dev/docs/typeship-api/errors#checks_failed" } ], "checks": [ { "name": "npm test", "source": "customer", "required": true, "status": "failed", "reason": "2 tests failed in tracking.test.ts.", "commit_sha": "0123456789abcdef0123456789abcdef01234567", "url": "https://github.com/parcel-example/parcel-client/actions/runs/1002", "observed_at": "2026-09-23T08:40:00Z" } ], "changes": { "changelog": "Add shipment tracking.", "breaking_count": 0 }, "head_sha": "0123456789abcdef0123456789abcdef01234567", "pull_request": { "url": "https://github.com/parcel-example/parcel-client/pull/12", "number": 12 }, "generation_id": "gen_7h2p5d9c3m8w1k6q", "release_id": null, "conflicts": null, "customized_files": 2, "history_recovery": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:40:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "MergedDraft": { "summary": "A merged Draft and the release it created", "value": { "id": "drf_3q7m1v8k2p5d9h4c", "object": "draft", "target_id": "tgt_5m8q2v7k1p9d4h6c", "project_id": "prj_4k8m2v7q1p9d5h6c", "status": "merged", "version_next": "1.1.0", "version_source": null, "compatibility": null, "version": null, "errors": [], "checks": [], "changes": null, "head_sha": "0123456789abcdef0123456789abcdef01234567", "pull_request": { "url": "https://github.com/parcel-example/parcel-client/pull/12", "number": 12 }, "generation_id": null, "release_id": "rel_7m2q8v4k1p9d5h6c", "conflicts": null, "customized_files": null, "history_recovery": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-24T10:00:00Z", "request_id": "req_3k8m1v6q9p2d7h4c" } }, "DraftList": { "summary": "A Target's Drafts, newest first", "value": { "object": "list", "data": [ { "id": "drf_3q7m1v8k2p5d9h4c", "object": "draft", "target_id": "tgt_5m8q2v7k1p9d4h6c", "project_id": "prj_4k8m2v7q1p9d5h6c", "status": "merged", "version_next": "1.1.0", "version_source": null, "compatibility": null, "version": null, "errors": [], "checks": [], "changes": null, "head_sha": "0123456789abcdef0123456789abcdef01234567", "pull_request": { "url": "https://github.com/parcel-example/parcel-client/pull/12", "number": 12 }, "generation_id": null, "release_id": "rel_7m2q8v4k1p9d5h6c", "conflicts": null, "customized_files": null, "history_recovery": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-24T10:00:00Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_3k8m1v6q9p2d7h4c" } } } }, "paths": { "/projects": { "post": { "operationId": "createProject", "tags": [ "projects" ], "summary": "Create a Project", "description": "Creates a Project from a URL or GitHub Spec.\nAutomatic generation is enabled by default for a saved Project.\n\nFree includes one saved Project, all selected Targets, and the first 25 operations per Target, with regeneration, history, delivery pull requests, and previews. Pro supports additional Projects and all operations. One-shot generation does not use a Project slot.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" }, "examples": { "url": { "summary": "Project from a URL", "value": { "name": "Parcel API", "spec": { "source": { "type": "url", "url": { "url": "https://api.parcel.example/openapi.json" } } }, "targets": [ { "name": "Parcel CLI", "type": "cli", "deliveries": [ { "type": "repository", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client", "module_path": "github.com/parcel-example/parcel-client", "publish_on_merge": false } } ] } ] } }, "repository": { "summary": "Project from a repository", "value": { "name": "Parcel API", "spec": { "source": { "type": "repository", "repository": { "provider": "github", "identifier": "parcel-example/api", "path": "openapi.yaml" } } }, "targets": [ { "name": "Parcel MCP", "type": "mcp", "deliveries": [ { "type": "hosted_mcp" } ] } ] } } } } } }, "responses": { "201": { "description": "Created.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" }, "examples": { "Project": { "$ref": "#/components/examples/Project" } } } } }, "400": { "description": "Invalid name, Spec source, or field value.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ValidationError": { "$ref": "#/components/examples/ValidationError" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "The plan does not include another project or the requested target configuration.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PlanError": { "$ref": "#/components/examples/PlanError" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "A Delivery conflicts, or the key identifies changed intent.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The configured source could not be read and analyzed, so the project was not created.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Project setup failed unexpectedly; the key reservation is released.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listProjects", "tags": [ "projects" ], "summary": "List Projects", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A page of projects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectList" }, "examples": { "ProjectList": { "$ref": "#/components/examples/ProjectList" }, "MoreProjects": { "$ref": "#/components/examples/MoreProjects" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A list query parameter is unknown, repeated, empty, or invalid, or the cursor is not for this list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "QueryValidationError": { "$ref": "#/components/examples/QueryValidationError" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/projects/{project_id}": { "get": { "operationId": "getProject", "tags": [ "projects" ], "summary": "Get a Project", "description": "Returns the Project's settings and Spec ID. List its Targets separately to retrieve Target configuration and Deliveries.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" }, "examples": { "Project": { "$ref": "#/components/examples/Project" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateProject", "tags": [ "projects" ], "summary": "Update a Project", "description": "Omitted fields keep their current values. A supplied config replaces the entire stored object; null or an empty object clears it.\nWith auto_generate enabled, changing shared config queues a Generation for each Target whose effective config changes. A queued or running Target reuses that Generation.\nOmitting If-Match applies the update to the current resource; with If-Match, a stale ETag returns 412 precondition_failed without saving.\n\nA `409 target_busy` means a Target is publishing. Retrieve the Project, wait for publishing to finish, reconcile your update, and retry.\nA `502 follow_up_failed` means the Project was saved, but an obsolete Draft pull request could not be retired. Retrieve the Project and retry the same update to finish retiring reviews if that update is still desired.\nSee [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false, "confirmationRecommended": true }, "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectRequest" }, "examples": { "settings": { "summary": "Disable automatic generation", "value": { "auto_generate": false } }, "clearConfig": { "summary": "Clear shared defaults", "value": { "config": null } } } } } }, "responses": { "200": { "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" }, "examples": { "UpdatedProject": { "$ref": "#/components/examples/UpdatedProject" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The plan does not include this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A Target is publishing, so the Project cannot be changed yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The proposed source, patches, or GraphQL configuration could not be analyzed, so the project was not changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } }, "delete": { "operationId": "deleteProject", "tags": [ "projects" ], "summary": "Delete a Project", "description": "A `502 repository_unavailable` means the Project was not deleted because its Draft pull requests could not be retired. Retry deletion to finish retiring the remaining reviews. Repeating a completed deletion returns `404`.\nSee [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false, "confirmationRecommended": true }, "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedProject" }, "examples": { "DeletedProject": { "$ref": "#/components/examples/DeletedProject" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/projects/{project_id}/generate": { "post": { "operationId": "generateProject", "tags": [ "projects" ], "summary": "Generate a Project's Targets", "description": "Queues one Generation per active Target and returns their IDs. Retrieve each Generation until its status moves from `queued` to `running` and then `completed` or `failed`. `completed` means generated files are saved; check Delivery and Draft status separately for repository delivery and pull requests. A Target already queued or running is returned without starting another Generation. A `409 targets_inactive` means the Project has no active Target to generate. A matching Idempotency-Key replay returns the same Generations with their current statuses.\n\nIf the package already matches a destination and no Draft is open, delivery creates no commit, branch, or pull request. An existing Draft stays open. Automatic generation uses the same workflow.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true, "confirmationRecommended": true }, "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateProjectRequest" }, "examples": { "target": { "summary": "Generate the Target whose conflict decisions were saved", "value": { "target_id": "tgt_5m8q2v7k1p9d4h6c" } }, "all": { "summary": "Generate every active Target", "value": {} } } } } }, "responses": { "202": { "description": "One Generation per selected Target, initially queued or returned from an existing run. Retrieve each Generation for its current status and generated files.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationBatch" }, "examples": { "GenerationBatch": { "$ref": "#/components/examples/GenerationBatch" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "The project is outside the organization's active Free slot.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The key identifies changed intent.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The Spec is over 10 MB, or an inline Spec is over 4 MB; send large Specs by URL.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The Spec could not be resolved or understood.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Generation or pull-request setup failed unexpectedly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/specs/{spec_id}": { "get": { "operationId": "getSpec", "tags": [ "specs" ], "summary": "Get a Spec", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/SpecId" } ], "responses": { "200": { "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The Spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Spec" }, "examples": { "Spec": { "$ref": "#/components/examples/Spec" }, "RepositorySpec": { "$ref": "#/components/examples/RepositorySpec" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateSpec", "tags": [ "specs" ], "summary": "Update a Spec", "description": "Resolves the source files before saving the update and records a new Spec Revision when the source changes.\nOmitted fields remain unchanged; supplied objects and arrays replace the whole field.\nWith Project auto_generate enabled, saving changed patches queues a Generation for each active Target. A queued or running Target reuses that Generation. An unchanged patch list does not queue generation.\nThe response is the saved Spec, not a generation result. List Generations with project_id to observe automatic runs. With auto_generate disabled, call projects generate after saving patches.\nPatch-only changes keep the existing source revision. A `502 follow_up_failed` means the patches were saved but generation could not be queued. This failure is not retryable: the same Idempotency-Key replays the failure for 24 hours, and re-saving unchanged patches does not queue generation. Retrieve the Spec and call projects generate with a new Idempotency-Key.\nIf the Spec or its Project configuration changes during validation, returns 409 resource_changed without saving the rejected update. Retrieve the current Spec and Project, reconcile your changes,\nand submit a new request with a new Idempotency-Key if using one.\n\nSee [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/SpecId" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecUpdateRequest" }, "examples": { "url": { "summary": "Use a URL Spec", "value": { "source": { "type": "url", "url": { "url": "https://api.parcel.example/openapi.json" } } } }, "repository": { "summary": "Use a repository Spec", "value": { "source": { "type": "repository", "repository": { "provider": "github", "identifier": "parcel-example/api", "path": "openapi.yaml" } } } } } } } }, "responses": { "200": { "description": "The updated Spec. Automatic generation, when queued, continues after this response.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Spec" }, "examples": { "Spec": { "$ref": "#/components/examples/Spec" }, "RepositorySpec": { "$ref": "#/components/examples/RepositorySpec" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The Spec or Project configuration changed during validation, or the key identifies changed intent.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/specs/{spec_id}/refresh": { "post": { "operationId": "refreshSpec", "tags": [ "specs" ], "summary": "Refresh a Spec", "description": "Fetches the configured source now and creates a new Spec Revision only when its content changes. Diagnostics then reads that revision. If automatic generation is enabled, refresh queues generation for active Targets even when the source is unchanged. A `502 follow_up_failed` means the new Spec Revision was recorded but generation could not be queued.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "name": "spec_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SpecId" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The refreshed Spec. Automatic generation, when queued, continues after this response.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Spec" }, "examples": { "Spec": { "$ref": "#/components/examples/Spec" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The key identifies changed intent.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The configured source could not be fetched or analyzed, and no Spec Revision was recorded. `code` is spec_unreachable, spec_too_large, repository_disconnected, or spec_invalid, and `message` quotes the reason from your source.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/spec-revisions": { "get": { "operationId": "listSpecRevisions", "tags": [ "spec_revisions" ], "summary": "List Spec Revisions", "description": "Lists Spec Revisions, newest first. Source content is not included; list a revision's files with listSpecRevisionFiles.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" }, { "name": "spec_id", "in": "query", "schema": { "$ref": "#/components/schemas/SpecId" }, "description": "Only revisions of this Spec." } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A page of Spec Revisions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecRevisionList" }, "examples": { "SpecRevisionList": { "$ref": "#/components/examples/SpecRevisionList" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A list query parameter is unknown, repeated, empty, or invalid, or the cursor is not for this list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/spec-revisions/{spec_revision_id}": { "get": { "operationId": "getSpecRevision", "tags": [ "spec_revisions" ], "summary": "Get a Spec Revision", "description": "Returns metadata for a saved Spec Revision with a Diagnostics summary. Pass `include=diagnostics` to add every Diagnostic, evaluated with the Spec's current patches and Diagnostic policy. Add `filter=blocking` to receive only the locations that fail the policy, which is what to fix when `diagnostic_summary.status` is blocked. List its source files and resolved document with listSpecRevisionFiles.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/SpecRevisionId" }, { "name": "include", "in": "query", "schema": { "type": "string", "enum": [ "diagnostics" ] }, "description": "Add related data to the response. `diagnostics` adds the `diagnostics` and `patch_diagnostics` arrays." }, { "name": "filter", "in": "query", "description": "Narrow the included Diagnostics to matching locations. Requires include=diagnostics. blocking: locations that fail the Diagnostic policy. introduced: locations new since the baseline. A Diagnostic with no matching location is omitted. diagnostic_summary always describes the complete revision.", "schema": { "type": "string", "enum": [ "blocking", "introduced" ] } } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The Spec Revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecRevisionResponse" }, "examples": { "SpecRevision": { "$ref": "#/components/examples/SpecRevision" }, "SpecRevisionWithDiagnostics": { "$ref": "#/components/examples/SpecRevisionWithDiagnostics" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/spec-revisions/{spec_revision_id}/files": { "get": { "operationId": "listSpecRevisionFiles", "tags": [ "spec_revisions" ], "summary": "List a Spec Revision's files", "description": "Lists the captured source files and the resolved document Typeship generated from, ordered by path. Read content with getFile.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/SpecRevisionId" }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A page of files, ordered by path, without content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecRevisionFileList" }, "examples": { "SpecRevisionFileList": { "$ref": "#/components/examples/SpecRevisionFileList" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A query parameter is unknown, repeated, empty, or invalid, or the cursor belongs to a different file or collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/targets": { "post": { "operationId": "createTarget", "tags": [ "targets" ], "summary": "Create a Target", "description": "Creates a Target with its own configuration, Deliveries, and release history. Multiple Targets can use the same generator.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetCreateRequest" }, "examples": { "repository": { "summary": "Deliver a CLI to GitHub", "value": { "project_id": "prj_4f8k2m7x9q1v6b3n", "name": "Parcel CLI", "type": "cli", "config": { "cli": { "command_name": "parcel" } }, "deliveries": [ { "type": "repository", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client", "module_path": "github.com/parcel-example/parcel-client", "publish_on_merge": false } } ] } }, "hosted": { "summary": "Host an MCP server", "value": { "project_id": "prj_4f8k2m7x9q1v6b3n", "name": "Parcel MCP", "type": "mcp", "deliveries": [ { "type": "hosted_mcp" } ] } }, "both": { "summary": "Deliver an MCP package and hosted server", "value": { "project_id": "prj_4f8k2m7x9q1v6b3n", "name": "Parcel MCP", "type": "mcp", "deliveries": [ { "type": "repository", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client", "module_path": "github.com/parcel-example/parcel-client", "publish_on_merge": false } }, { "type": "hosted_mcp" } ] } } } } } }, "responses": { "201": { "description": "Target created.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetResponse" }, "examples": { "CreatedTarget": { "$ref": "#/components/examples/CreatedTarget" } } } } }, "400": { "description": "Invalid Target, Delivery, or Spec association.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "The plan does not include another active Target with this generator.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "A repository tree is already owned, or the key identifies changed intent.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The repository provider is not available.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "operationId": "listTargets", "tags": [ "targets" ], "summary": "List Targets", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" }, { "name": "project_id", "in": "query", "schema": { "$ref": "#/components/schemas/ProjectId" }, "description": "Only Targets in this Project." } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A page of configured Targets, including disabled Targets, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetList" }, "examples": { "TargetList": { "$ref": "#/components/examples/TargetList" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A list query parameter is unknown, repeated, empty, or invalid, or the cursor is not for this list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/targets/{target_id}": { "get": { "operationId": "getTarget", "tags": [ "targets" ], "summary": "Get a Target", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/TargetId" } ], "responses": { "200": { "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The Target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetResponse" }, "examples": { "Target": { "$ref": "#/components/examples/Target" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateTarget", "tags": [ "targets" ], "summary": "Update a Target", "description": "Omitted fields keep their current values. Supplied config and checks replace their complete stored values. Change Deliveries with createDelivery, updateDelivery, and deleteDelivery.\nWith Project auto_generate enabled, changing Target config or checks queues that Target's Generation. A queued or running Target reuses that Generation.\nOmitting If-Match applies the update to the current resource; with If-Match, a stale ETag returns 412 precondition_failed without saving.\nSelect the next version through PATCH /drafts/{draft_id} on the Target's draft_id.\n\nA `409 target_busy` means the Target is publishing; wait for it to finish. A `409 delivery_conflict` means another Target owns the requested repository tree; retrieve both Targets, choose a free destination, and retry.\nA `502 follow_up_failed` means the update was saved, but retiring an obsolete review or regenerating the Target failed. Retrieve the Target and follow the error's retryable and suggested_action fields.\nSee [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/TargetId" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetUpdateRequest" }, "examples": { "disable": { "summary": "Disable a Target", "value": { "status": "disabled" } }, "prerelease": { "summary": "Release as prereleases", "value": { "release_channel": "prerelease" } } } } } }, "responses": { "200": { "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Updated Target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetResponse" }, "examples": { "UpdatedTarget": { "$ref": "#/components/examples/UpdatedTarget" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Invalid Target update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The plan does not include another active Target with this generator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A repository tree is already owned by another Target, or the Target is currently publishing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The repository provider is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } }, "delete": { "operationId": "deleteTarget", "tags": [ "targets" ], "summary": "Delete a Target", "description": "Deletes a Target with no Generation history, release history, or active Draft. A `409 resource_has_dependencies` means one of those resources still depends on it. Retrieve the Target, disable it instead, or resolve the dependency before retrying.\n\nSee [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": true, "confirmationRecommended": true }, "parameters": [ { "$ref": "#/components/parameters/TargetId" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Target deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedTarget" }, "examples": { "DeletedTarget": { "$ref": "#/components/examples/DeletedTarget" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Release state depends on this Target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/targets/{target_id}/adopt": { "post": { "operationId": "adoptTarget", "tags": [ "targets" ], "summary": "Adopt a package release", "description": "Checks the repository tag, package metadata, and registry artifact, then records the package as an Imported latest release. Opens the first Typeship Draft at the next major version; review it to establish the baseline for preserving existing code.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true, "confirmationRecommended": true }, "parameters": [ { "$ref": "#/components/parameters/TargetId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetAdoption" }, "examples": { "published": { "summary": "Adopt a verified published package", "value": { "version": "1.0.0", "tag": "v1.0.0" } } } } } }, "responses": { "201": { "description": "Verified Imported latest release.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseResponse" }, "examples": { "AdoptedRelease": { "$ref": "#/components/examples/AdoptedRelease" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Adoption input is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Target already has a release, the key identifies changed intent, or its repository is disconnected.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Tag, package, or registry provenance could not be verified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/deliveries": { "post": { "operationId": "createDelivery", "tags": [ "deliveries" ], "summary": "Create a Delivery", "description": "Adds a repository or hosted MCP Delivery to a Target. A Target has at most one Delivery of each type; a `409 delivery_exists` means it already has one, so update that Delivery instead.\nWith Project auto_generate enabled, adding a Delivery queues the Target's Generation. A queued or running Target reuses that Generation.\n\nA `409 delivery_conflict` means another Target owns the requested repository directory. A `409 target_busy` means the Target is publishing; wait for it to finish.\nA `502 follow_up_failed` means the Delivery was saved, but retiring an obsolete review or regenerating the Target failed. Get the Delivery and follow the error's retryable and suggested_action fields.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryCreateRequest" }, "examples": { "repository": { "summary": "Deliver the Parcel CLI to GitHub", "value": { "target_id": "tgt_5m8q2v7k1p9d4h6c", "type": "repository", "repository": { "provider": "github", "identifier": "parcel-example/parcel-client", "module_path": "github.com/parcel-example/parcel-client", "publish_on_merge": false } } }, "hosted": { "summary": "Host an MCP Target", "value": { "target_id": "tgt_7k2q9v4m1p8d5h3c", "type": "hosted_mcp" } } } } } }, "responses": { "201": { "description": "Created Delivery.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryResponse" }, "examples": { "Delivery": { "$ref": "#/components/examples/Delivery" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "The Target already has a Delivery of this type, another Target owns the repository directory, the Target is publishing, or the key identifies changed intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The repository provider is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } }, "get": { "operationId": "listDeliveries", "tags": [ "deliveries" ], "summary": "List Deliveries", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" }, { "name": "target_id", "in": "query", "schema": { "$ref": "#/components/schemas/TargetId" }, "description": "Only Deliveries of this Target." } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A page of Deliveries, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryList" }, "examples": { "DeliveryList": { "$ref": "#/components/examples/DeliveryList" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A list query parameter is unknown, repeated, empty, or invalid, or the cursor is not for this list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/deliveries/{delivery_id}": { "get": { "operationId": "getDelivery", "tags": [ "deliveries" ], "summary": "Get a Delivery", "description": "Returns the configured repository or hosted MCP Delivery for a Target. A Delivery in another organization returns 404 resource_not_found.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/DeliveryId" } ], "responses": { "200": { "description": "The Delivery.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryResponse" }, "examples": { "Delivery": { "$ref": "#/components/examples/Delivery" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateDelivery", "tags": [ "deliveries" ], "summary": "Update a Delivery", "description": "Replaces a repository Delivery's settings. Omitted optional settings reset to their defaults. Hosted MCP Deliveries have no settings to update.\nWith Project auto_generate enabled, changing a Delivery queues the Target's Generation. A queued or running Target reuses that Generation.\nOmitting If-Match applies the update to the current Delivery; with If-Match, a stale ETag returns 412 precondition_failed without saving.\n\nA `409 delivery_conflict` means another Target owns the requested repository directory. A `409 target_busy` means the Target is publishing; wait for it to finish.\nA `502 follow_up_failed` means the Delivery was saved, but retiring an obsolete review or regenerating the Target failed. Get the Delivery and follow the error's retryable and suggested_action fields.\nSee [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/DeliveryId" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryUpdateRequest" }, "examples": { "publish": { "summary": "Publish the Parcel CLI on merge", "value": { "repository": { "provider": "github", "identifier": "parcel-example/parcel-client", "module_path": "github.com/parcel-example/parcel-client", "publish_on_merge": true } } } } } } }, "responses": { "200": { "description": "Updated Delivery.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryResponse" }, "examples": { "Delivery": { "$ref": "#/components/examples/Delivery" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Another Target owns the repository directory, or the Target is publishing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The repository provider is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } }, "delete": { "operationId": "deleteDelivery", "tags": [ "deliveries" ], "summary": "Delete a Delivery", "description": "Removes a Delivery from its Target. Removing a repository Delivery retires the Target's open Draft pull request; removing a hosted MCP Delivery stops serving its URL. Recreating the type later allocates a new ID and, for hosted MCP, a new URL.\n\nA `409 target_busy` means the Target is publishing; wait for it to finish. A `502 follow_up_failed` means the Delivery was removed, but retiring an obsolete review or regenerating the Target failed.\nSee [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": true, "confirmationRecommended": true }, "parameters": [ { "$ref": "#/components/parameters/DeliveryId" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Delivery deleted.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedDelivery" }, "examples": { "DeletedDelivery": { "$ref": "#/components/examples/DeletedDelivery" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The Target is publishing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/generations/{generation_id}": { "get": { "operationId": "getGeneration", "tags": [ "generations" ], "summary": "Get a Generation", "description": "Returns the status of that Generation. `queued` and `running` mean generation is still in progress. `completed` means generated files are saved, not that repository delivery or a Draft is complete. List its files with listGenerationFiles and read each with getFile.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/GenerationId" } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationResponse" }, "examples": { "Generation": { "$ref": "#/components/examples/Generation" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/generations": { "get": { "operationId": "listGenerations", "tags": [ "generations" ], "summary": "List Generations", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" }, { "name": "project_id", "in": "query", "schema": { "$ref": "#/components/schemas/ProjectId" }, "description": "Only Generations in this Project." }, { "name": "target_id", "in": "query", "schema": { "$ref": "#/components/schemas/TargetId" }, "description": "Only Generations of this Target." }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/GenerationStatus" }, "description": "Only Generations with this status." } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A page of generations, newest first, without files.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationList" }, "examples": { "GenerationList": { "$ref": "#/components/examples/GenerationList" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A list query parameter is unknown, repeated, empty, or invalid, or the cursor belongs to a different collection or target filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/generations/{generation_id}/files": { "get": { "operationId": "listGenerationFiles", "tags": [ "generations" ], "summary": "List a Generation's files", "description": "Lists the generated package's files, ordered by path. Read content with getFile.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/GenerationId" }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A page of files, ordered by path, without content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileList" }, "examples": { "GenerationFileList": { "$ref": "#/components/examples/GenerationFileList" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A query parameter is unknown, repeated, empty, or invalid, or the cursor belongs to a different file or collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/drafts": { "get": { "operationId": "listDrafts", "tags": [ "drafts" ], "summary": "List Drafts", "description": "Lists open and merged Drafts, newest first. Each Target has one open Draft; each merge adds a merged Draft.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" }, { "name": "target_id", "in": "query", "schema": { "$ref": "#/components/schemas/TargetId" }, "description": "Only Drafts of this Target." }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/DraftStatus" }, "description": "Only Drafts with this status." } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A page of Drafts, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftList" }, "examples": { "DraftList": { "$ref": "#/components/examples/DraftList" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A list query parameter is unknown, repeated, empty, or invalid, or the cursor is not for this list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/drafts/{draft_id}": { "get": { "operationId": "getDraft", "tags": [ "drafts" ], "summary": "Get a Draft", "description": "Returns the Draft's status. An open Draft also reports its typed reason when action is required, next version and its source, compatibility and version assessment, blocking errors, checks, and conflict counts. The response carries an `ETag`; send it in `If-Match` when updating the Draft to avoid changing a newer version selection.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/DraftId" } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "description": "The Draft.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponse" }, "examples": { "Draft": { "$ref": "#/components/examples/Draft" }, "BlockedDraft": { "$ref": "#/components/examples/BlockedDraft" }, "MergedDraft": { "$ref": "#/components/examples/MergedDraft" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateDraft", "tags": [ "drafts" ], "summary": "Update a Draft", "description": "Checks your version choice against the required version bump, then regenerates the existing Draft pull request.\n\nSend the Draft's `ETag` in `If-Match` to reject an intervening change with 412 precondition_failed before saving or regenerating. Omitting `If-Match` applies the selection to the current Draft. version_next is required; null restores automatic selection.\n\nA `502` response means the selected version was saved, but regeneration failed. Follow the error's retryable and suggested_action fields. Repeating an unfinished selection resumes generation; repeating a completed selection starts no new work. If using If-Match, retrieve the Draft and confirm the saved selection before retrying with its current ETag.\nA `409 draft_merged` means the Draft merged; retrieve the Target and select a version on its `draft_id`. A `409 target_busy` means the Target is publishing; wait and retry. A `409 version_occupied` means the version is already released; retrieve the Draft and releases, choose a new version, and retry.\nSee [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/DraftId" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftUpdateRequest" }, "examples": { "exact": { "summary": "Select an exact version", "value": { "version_next": "1.1.0" } }, "automatic": { "summary": "Return to automatic selection", "value": { "version_next": null } } } } } }, "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "description": "The updated Draft.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponse" }, "examples": { "UpdatedDraft": { "$ref": "#/components/examples/UpdatedDraft" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Invalid Draft selection or If-Match header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The Draft merged, the Target is busy, or the version is already occupied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The Draft's version selection changed since the ETag in If-Match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PreconditionFailed": { "$ref": "#/components/examples/PreconditionFailed" } } } } }, "422": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Version is invalid or below the cumulative required bump.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/drafts/{draft_id}/files": { "get": { "operationId": "listDraftFiles", "tags": [ "drafts" ], "summary": "List a Draft's files", "description": "Lists the Draft's files that differ from the last merged package or need a conflict decision, ordered by path, without file content. Each conflict names its kind, the saved decision, and the sides you can read with getFile. With `filter=history`, lists files affected by a default-branch history rewrite; the list is empty when none is pending.\n\nReturns `409 resource_changed` while Typeship is carrying the Draft's latest commit forward (status working), or when the Draft changes between pages.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/DraftId" }, { "name": "filter", "in": "query", "description": "conflicted: conflicts only. customized: files that differ from the last merged package. history: files affected by a default-branch history rewrite. Omit for conflicted and customized files.", "schema": { "type": "string", "enum": [ "conflicted", "customized", "history" ] } }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Draft files ordered by path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftFileList" }, "examples": { "DraftFileList": { "$ref": "#/components/examples/DraftFileList" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A query parameter is unknown, repeated, or invalid, or the cursor belongs to a different listing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The Draft has an unintegrated commit or changed between pages; retrieve the Draft and list again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/drafts/{draft_id}/resolve": { "post": { "operationId": "resolveDraft", "tags": [ "drafts" ], "summary": "Resolve Draft conflicts", "description": "Resolves conflicts on the Draft's head_sha: keep yours or generated, or supply final content as text or, for binary files, base64. Choosing generated for a customized path replaces it with the generated file, or deletes a Draft-only file.\n\nConflict decisions are saved together and can be replaced until applied. Choosing generated for customized paths commits those changes together on the Draft branch. Returns the Draft. When every conflict has a decision, `conflicts.decided` equals `conflicts.total` and Typeship continues the Draft and runs checks. Paths that already match the Draft change nothing.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": true, "confirmationRecommended": true }, "parameters": [ { "$ref": "#/components/parameters/DraftId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResolveRequest" }, "examples": { "combined": { "summary": "Keep a combined version of both edits", "value": { "expected_head_sha": "0123456789abcdef0123456789abcdef01234567", "resolutions": [ { "path": "src/index.ts", "keep": "content", "mode": "100644", "content": "export { ParcelClient } from \"./client.js\";\nexport type { Shipment, Label } from \"./types.js\";\nexport { createParcelClient } from \"./helper.js\";\n" } ] } }, "generated": { "summary": "Remove a Draft-only file", "value": { "expected_head_sha": "0123456789abcdef0123456789abcdef01234567", "resolutions": [ { "path": "src/helper.ts", "keep": "generated" } ] } } } } } }, "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The Draft with the decisions saved or committed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponse" }, "examples": { "ResolvedDraft": { "$ref": "#/components/examples/ResolvedDraft" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Invalid decisions or paths that are not current conflicts or customizations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The Draft merged, has no pending change, changed since you read it, or has an unintegrated commit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/drafts/{draft_id}/recover": { "post": { "operationId": "recoverDraft", "tags": [ "drafts" ], "summary": "Recover a Draft's history", "description": "When the Draft has status `action_required` and reason `history_rewritten`, review affected files with `listDraftFiles` and `filter=history`, then approve with the Draft's `history_recovery` revisions. Approval saves the recovery without changing Git and returns the Draft; the next generation rebuilds it from the rewritten default branch. The previous Draft branch stays available, and overlapping code comes back as conflicts to resolve. A rewritten Draft branch alone needs no approval.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true, "confirmationRecommended": true }, "parameters": [ { "$ref": "#/components/parameters/DraftId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftRecoverRequest" }, "examples": { "approve": { "summary": "Approve the reviewed revisions", "value": { "expected_default_sha": "89abcdef0123456789abcdef0123456789abcdef", "expected_head_sha": "0123456789abcdef0123456789abcdef01234567" } } } } } }, "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The Draft. history_recovery is null once recovery is approved or when none was needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponse" }, "examples": { "ResolvedDraft": { "$ref": "#/components/examples/ResolvedDraft" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Invalid recovery request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The Draft merged, repository history changed since review, or the Target is busy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/releases": { "get": { "operationId": "listReleases", "tags": [ "releases" ], "summary": "List Releases", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" }, { "name": "target_id", "in": "query", "schema": { "$ref": "#/components/schemas/TargetId" }, "description": "Only releases of this Target." } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Releases, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseList" }, "examples": { "ReleaseList": { "$ref": "#/components/examples/ReleaseList" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A list query parameter is unknown, repeated, empty, or invalid, or the cursor is not for this list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/releases/{release_id}": { "get": { "operationId": "getRelease", "tags": [ "releases" ], "summary": "Get a Release", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/ReleaseId" } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The release.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseResponse" }, "examples": { "Release": { "$ref": "#/components/examples/Release" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/releases/{release_id}/retry": { "post": { "operationId": "retryRelease", "tags": [ "releases" ], "summary": "Retry publishing a Release", "description": "Queues every failed or queued Publication of the release and starts its repository publishing workflow again. Publishing uses that release's version and accepted commit, even if a newer Draft or release exists. Completed Publications are not repeated.\n\nReturns `202` with the Release. Get the Release until each Publication reaches `completed` or `failed`.\n\nA `409 publication_not_retryable` means no Publication is queued or failed. A `502 repository_unavailable` means the repository publishing workflow could not be dispatched, and nothing was changed.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true, "confirmationRecommended": true }, "parameters": [ { "$ref": "#/components/parameters/ReleaseId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Publishing restarted; the release's retried Publications are queued.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseResponse" }, "examples": { "RetriedRelease": { "$ref": "#/components/examples/RetriedRelease" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Publishing is disabled, cannot be retried, lacks required metadata, or the key identifies changed intent.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/files/{file_id}": { "get": { "operationId": "getFile", "tags": [ "files" ], "summary": "Get a File", "description": "Returns one bounded chunk of an immutable file: at most 24 KiB, as UTF-8 text or, for binary bytes, base64. When next_cursor is not null, repeat the request with cursor and concatenate the chunks in order. A file ID always returns the same bytes.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/FileId" } }, { "name": "cursor", "in": "query", "description": "next_cursor from the preceding chunk of this file.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048, "pattern": "^[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "One chunk of the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" }, "examples": { "File": { "$ref": "#/components/examples/File" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A query parameter is unknown, repeated, empty, or invalid, or the cursor belongs to a different file or collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/generate": { "post": { "operationId": "generatePackage", "tags": [ "packages" ], "summary": "Generate a package", "description": "Returns one generated package without creating a Project.\n\nSupports [idempotent retries](https://typeship.dev/docs/typeship-api/idempotency); keyed responses include generated files in the replay cache.\n\nUse `download.url` to save the complete ZIP, verify `download.sha256`, and extract it into an empty directory. The link expires at `download.expires_at` and grants access to anyone who has it. CLI, MCP, and SDK calls supply an idempotency key automatically. Agents should request `fields=[\"download\",\"coverage\",\"warnings\",\"claim\"]` to keep the MCP result compact; files can exceed the response limit. Download the ZIP instead of repeating generation to retrieve omitted files.\n\nAnonymous and Free requests include the first 25 operations. Paid plans include all operations. Anonymous requests are rate limited by IP address. Check `coverage` for omitted operations; an invalid API key returns `401`.\n\nAn anonymous URL request without source headers may return `claim.url`. Sign in through that link within seven days to save the recipe as a Project.", "security": [ {}, { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateRequest" }, "examples": { "hostedSample": { "summary": "Runnable hosted sample", "value": { "spec": { "url": "https://typeship.dev/examples/petstore/openapi.yaml" }, "target": { "type": "cli" } } }, "parcelUrl": { "summary": "Fictional Parcel URL", "value": { "spec": { "url": "https://api.parcel.example/openapi.json" }, "target": { "type": "cli" }, "config": { "cli": { "command_name": "parcel" } } } }, "parcelInline": { "summary": "Inline Parcel Spec", "value": { "spec": { "inline": "openapi: 3.1.0\ninfo:\n title: Parcel API\n version: 1.0.0\nservers:\n - url: https://api.parcel.example\npaths:\n /shipments:\n get:\n operationId: listShipments\n responses:\n \"200\":\n description: Shipments\n content:\n application/json:\n schema:\n type: array\n items:\n type: object\n required: [shipment_id]\n properties:\n shipment_id:\n type: string\n" }, "target": { "type": "cli" }, "config": { "cli": { "command_name": "parcel" } } } } } } } }, "responses": { "200": { "description": "The generated package.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationResult" }, "examples": { "HostedSampleResult": { "$ref": "#/components/examples/HostedSampleResult" }, "GenerationResult": { "$ref": "#/components/examples/GenerationResult" } } } } }, "400": { "description": "The request body, Spec source, target selection, or package name is invalid.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "The key identifies changed intent.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IdempotencyConflict": { "$ref": "#/components/examples/IdempotencyConflict" } } } } }, "413": { "description": "The Spec is over 10 MB, or an inline Spec is over 4 MB; send large Specs by URL.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The Spec could not be resolved or understood.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "default": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/generate/download": { "get": { "operationId": "downloadPackage", "tags": [ "packages" ], "summary": "Download a generated package", "description": "Download the complete ZIP referenced by `packages_generate`'s `download.url`. Pass the token from that URL. No API key is needed; the token grants access only to that exact package until its replay window expires. Keep the token private.\n\nThe local MCP server saves this binary response to disk. On a hosted MCP connection, download the original URL directly to your workspace. Verify the ZIP against `download.sha256` before extracting it into an empty directory. Expired or invalid tokens return `404`; a new generation creates a new download.", "security": [ {} ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "name": "token", "in": "query", "required": true, "description": "Private download token from download.url in the generation result.", "schema": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" }, "example": "parcel_download_example_token_1234567890123" } ], "responses": { "200": { "description": "ZIP containing every file from the original generation, with package-relative paths.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/organization": { "get": { "operationId": "getOrganization", "tags": [ "organization" ], "summary": "Get the Organization", "description": "Returns the organization associated with your credential. The Typeship CLI uses this endpoint for `whoami`.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The authenticated organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" }, "examples": { "Organization": { "$ref": "#/components/examples/Organization" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api-keys": { "get": { "operationId": "listApiKeys", "tags": [ "api_keys" ], "summary": "List API keys", "description": "Lists key metadata and the last four characters of each key. Full keys are not returned. Create keys in the Console.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/PageCursor" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "revoked" ] }, "description": "Only keys with this status." } ], "responses": { "200": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A page of API keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyList" }, "examples": { "ApiKeyList": { "$ref": "#/components/examples/ApiKeyList" } } } } }, "400": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "A list query parameter is unknown, repeated, empty, or invalid, or the cursor is not for this list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api-keys/{api_key_id}": { "get": { "operationId": "getApiKey", "tags": [ "api_keys" ], "summary": "Get an API key", "description": "Returns the key summary and its ETag for conditional revocation.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "parameters": [ { "$ref": "#/components/parameters/ApiKeyId" } ], "responses": { "200": { "description": "The API key.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" }, "examples": { "ApiKey": { "$ref": "#/components/examples/ApiKey" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api-keys/{api_key_id}/revoke": { "post": { "operationId": "revokeApiKey", "tags": [ "api_keys" ], "summary": "Revoke an API key", "description": "Revokes a key immediately. The key stays listed with `status: revoked`. Repeating the request returns the same result.\n\nWith OAuth, members can revoke their own keys; organization admins can revoke any key. Organization API keys can revoke any key in their organization.\nSee [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.", "security": [ { "apiKey": [] } ], "x-typeship-agent": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false, "confirmationRecommended": true }, "parameters": [ { "$ref": "#/components/parameters/ApiKeyId" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "description": "The revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" }, "examples": { "RevokedApiKey": { "$ref": "#/components/examples/RevokedApiKey" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } } } }