DocumentationTypeship CLITypeship MCPTypeship SDKsAPI Reference
Console
Specs

Refresh a Spec from its configured source

POST
/specs/{spec_id}/refresh

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.

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

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

Response 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 and resolve 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. 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 generations GET

Next Page