Specs

A Spec is the OpenAPI or GraphQL description of your API connected to a Project. Typeship reads it to generate your Targets and check API changes. Each observed change becomes an immutable Spec Revision, so you can trace a Generation to the source it used.

A Spec can be:

• one OpenAPI or Swagger document;
• one GraphQL schema;
• a resolved graph of OpenAPI files connected by repository-relative $ref values; or
• a GraphQL schema composed from multiple SDL files with #import directives.

Use separate Projects for independently consumed APIs. Multiple files that describe one API belong to one Spec; unrelated APIs do not.

See Combine API documents when you have several OpenAPI roots or need to decide whether files belong in one Spec.

Sources

Connect a URL for a hosted specification, or connect GitHub to review source changes in pull requests.

A Spec has one entrypoint, either a URL or a file in a GitHub repository. A URL source may carry write-only fetch credentials. URL sources must resolve to public network addresses; loopback, private, link-local, carrier-grade NAT, and local-name destinations are rejected on the entrypoint, every redirect, and every referenced file. Put credentials in source request headers rather than the URL itself. A repository source uses the Typeship GitHub App and can participate in source pull-request review.

OpenAPI references may stay split across repository files. URL references must remain on the resolved entrypoint's origin. Configured source credentials are reused while the entrypoint stays on its configured origin; after any cross-origin redirect, they remain stripped from the redirect chain and referenced files.

Before accepting the graph, Typeship limits redirects, reference depth, cycles, file count, and total bytes. It never executes your code to produce a Spec.

For GraphQL, Typeship combines the imported SDL files into one schema. Endpoint, authentication, environment, title, and scalar settings live on the Spec because the schema itself cannot express them.

Updating a Spec

PATCH /specs/{spec_id} updates only the fields you supply. Each supplied object or array replaces that field; omitted siblings inside it do not survive, except for the URL credentials described below. Send at least one field.

For the same source URL, omitting source.headers preserves the write-only credentials. Supply null or {} to remove them. Changing the URL without supplying headers clears the old credentials.

For example, {"patches":[]} removes the Spec's patches while preserving its source, GraphQL settings, and diagnostic policy. {"graphql":{"title":"Parcel API"}} replaces the GraphQL settings, including any previously configured endpoint or authentication.

An update resolves and validates the source before saving. Send the Spec's ETag in an optional If-Match header to reject an intervening change with 412 precondition_failed. If another edit changes the Spec or its Project configuration during validation, Typeship returns 409 resource_changed and saves nothing from the rejected request. Retrieve both resources, reconcile your changes, and submit a new request with a new idempotency key if you use one. Sequential requests apply to the current state; replacing a field overwrites its previously accepted value. See conditional writes.

Spec Revisions

Each source change creates an immutable Spec Revision (srev_*). Use its ID to retrieve the resolved Spec and source files used by a Generation.

Changes to referenced files also create revisions and participate in source review and automatic generation.

An unchanged source keeps its current revision. Reverting an earlier change creates a new revision, so you can distinguish the revert from the original source.

The Console shows a file tree when a Spec has multiple source files. GET /spec-revisions/{spec_revision_id}/files lists each source file with its role (entrypoint or reference), plus the resolved document Typeship generated from. Each is a file with an ID. Read one with GET /files/{file_id} in bounded chunks, passing next_cursor as cursor until it is null.

Where each revision is used

Diagnostics, Spec patches, compatibility reviews, and generated Targets use the same Spec Revision. Compare their spec_revision_id values when checking that a review and package refer to the same source.

Free projects retain and diagnose the complete Spec. The Free cap applies when each Target is generated: the first 25 operations are included and the response states how many were omitted.