Specs

Get a Spec

GET
/specs/{spec_id}
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}$

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/specs/spec_2p8m4q7k1v9d6h3c"

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

Generate a Project's Targets POST

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. If 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.

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.