Docs

Register contracts

You can register contracts in the console, through the public API, or from a reviewed local discovery plan with assisted codebase setup. Every method creates an immutable draft that must be explicitly activated.

Register a declared contract when you want structural analysis to compare each observation with an explicit operation schema. Registration creates an immutable draft. Analysis changes only after an owner or admin activates that draft.

Before you begin

You need an integration with a direction and protocol, owner or admin access, and either an OpenAPI document or JSON Schema for one operation. Use representative route templates and event types, never concrete customer identifiers.

Choose the import

Use OpenAPI when one document contains several request, response, or webhook schemas. Use JSON Schema when you need to attach one schema to one method, route, event, payload location, and optional response status selector.

Seamward supports JSON and YAML in the console. The public API accepts JSON request bodies. OpenAPI import currently supports GET, POST, PUT, PATCH, and DELETE, JSON media types, local references, and the documented JSON Schema subset. Review the exact import boundaries before relying on composition or remote references.

Register a draft

  1. Open Integrations, select the integration, and open Contracts.
  2. Select Register contract or Register new version.
  3. Enter a unique declared version.
  4. Choose OpenAPI or JSON Schema for one operation, then paste the document.
  5. For JSON Schema, complete the stable operation selector.
  6. Submit the form. The new card appears as Draft and existing analysis continues using the active version.

An identical retry returns the existing immutable version, which makes recovery from a lost response safe. If registration returns contract_version_already_exists, the same declared version already has different document content or operation selectors. Choose a new immutable version label; do not overwrite the existing version.

Review and activate

Open each operation and inspect its method, route template, event type, payload location, status selector, and schema. When the version is correct, choose Activate version. A previous immutable version offers Roll back to this version.

Activation records a revision and audit event, supersedes the previous active version, and queues reanalysis in one transaction. If another deployment changed the active version first, refresh and review the new state before retrying.

Automate from CI

Create a workspace API key with contracts:write and contracts:activate, store the one-time sw_api_... secret in CI, then call:

Code example

POST /v1/integrations/{integrationId}/contractsPOST /v1/integrations/{integrationId}/contracts/{contractVersionId}/activate

The registration call creates a draft. The activation body must include the active version CI reviewed as expectedActiveContractVersionId, including null for the first activation. A stale precondition returns 409 instead of replacing another pipeline's version.

Include expectedScope with the Integration direction and protocol in every new registration request. The API rejects a mismatch before storing the draft. This guard is optional only for backward compatibility with earlier API clients; the Seamward CLI and console always send it.

See the Contract API reference for complete request bodies, scopes, responses, and errors.

Diagnose a mismatch

When registered operations do not match observations, compare these fields in order:

  1. Integration direction and protocol.
  2. HTTP method and normalized route template.
  3. Event type when the contract declares one.
  4. Payload location: request, response, or message.
  5. Response status selection: exact status, status class, then default.

Use templates such as /customers/{customerId} or /customers/:customerId; Seamward normalizes both forms. If no operation matches, Seamward does not silently claim that an observed baseline is the registered contract. Review the collector metadata and contract selector, then register and activate a corrected immutable version.