Refresh a Spec
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.
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
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.
^[!-~]+$1 <= length <= 255Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/specs/spec_2p8m4q7k1v9d6h3c/refresh"{ "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"}Update a Spec PATCH
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](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
List Spec Revisions GET
Lists Spec Revisions, newest first. Source content is not included; list a revision's files with listSpecRevisionFiles.