DocumentationTypeship CLITypeship MCPTypeship SDKsAPI Reference
Console
Specs

Update and resolve a Spec

PATCH
/specs/{spec_id}

Resolves the source files before saving the update and records a new Spec Revision when the source changes. Omitted fields remain unchanged; supplied objects and arrays replace the whole field. If 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, and submit a new request with a new Idempotency-Key if using one.

See conditional writes for ETag and If-Match.

Authorization

apiKey
AuthorizationBearer <token>

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.

In: header

Path Parameters

spec_id*string

Unique identifier for a project's logical API Spec.

Match^spec_[a-z0-9]{16}$

Header Parameters

If-Match?string

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.

Length1 <= length <= 1024
Idempotency-Key?string

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.

Match^[!-~]+$
Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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.

Properties1 <= properties

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/specs/spec_2p8m4q7k1v9d6h3c" \  -H "Content-Type: application/json" \  -d '{    "source": {      "type": "url",      "url": {        "url": "https://api.parcel.example/openapi.json"      }    }  }'

{  "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"}

Get a Spec GET

Previous Page

Refresh a Spec from its configured source POST

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.