Update a Spec
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.
With 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.
The 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.
Patch-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.
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 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
Unique identifier for a project's logical API Spec.
^spec_[a-z0-9]{16}$Header Parameters
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.
1 <= length <= 1024Identifies 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.
^[!-~]+$1 <= length <= 255Request 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.
1 <= propertiesResponse Body
application/json
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 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. A `502 follow_up_failed` means the new Spec Revision was recorded but generation could not be queued.