Seamward API
To validate collector credentials without recording observations, use Check a connection. This checks authentication, not application health.
The Seamward HTTP API receives redacted observation evidence and manages immutable integration contracts. This reference documents every supported endpoint exactly as it behaves; the examples on these pages are checked against machine-readable contracts and the Fastify API.
Base URL
Code example
https://api.seamward.comCustom and self-hosted deployments use their own base URL; it is the same value you would set as SEAMWARD_INGEST_URL for the collector. Remote endpoints require HTTPS. Requests and responses are JSON, and the current observation envelope is versioned (envelopeVersion: "0.3"). The API continues to read unchanged 0.1 and 0.2 envelopes during collector and strict-reader upgrades. See version compatibility before upgrading.
All endpoints reject malformed JSON with 400 invalid_request and bodies above
1 MiB with 413 request_too_large, before route processing. These common errors
are included in each available endpoint’s machine-readable error contract.
Credentials
Collector credentials deliver observations and check their own connection. They cannot read workspace evidence or manage contracts:
| Credential | Format | Secret? | Grants |
|---|---|---|---|
| Connection key | sw_conn_v1.<integration-token>.<integration-id> | No | Identifies and routes to one Integration |
| Ingest token | sw_ing_ + 43 chars | Yes | Writes observations, checks its own connection and signs requests |
| Workspace API key | sw_api_ + 43 chars | Yes | Only the Integration inventory, observation, and contract scopes selected |
| Setup access token | OAuth bearer token | Yes | One browser-approved environment and setup scopes |
Each Integration receives its Connection key and one ingest token during setup. Workspace owners create API keys with the workspace key management endpoint. Secrets are shown once, stored only as SHA-256 hashes, and can be rotated or revoked. Setup tokens come from browser authorization and are stored outside the project. An ingest token never authenticates a contract request, and an API key never authenticates ingestion.
What's available
| Endpoint | Purpose | Status |
|---|---|---|
GET /v1/collector/connection | Check collector credentials | Available |
POST /ingest | Ingest observations in signed batches | Available |
GET /v1/setup/context | Get approved setup context | Available |
POST /v1/setup/integrations/preview | Preview Integration changes | Available |
POST /v1/setup/integrations/apply | Apply a reviewed setup | Available |
GET /v1/setup/integrations/operations/{operationId} | Read setup operation status | Available |
POST /v1/setup/integrations/{integrationId}/deletion-preview | Preview Integration deletion | Available |
DELETE /v1/setup/integrations/{integrationId} | Delete an Integration | Available |
GET /v1/setup/integrations/{integrationId}/deletions/{operationId} | Read deletion status | Available |
GET /v1/observations | List observations | Available |
GET /v1/observations/{observationId} | Get one observation | Available |
GET /v1/observations/usage | Get usage | Available |
GET /v1/integrations/{integrationId}/contracts | List contracts | Available |
POST /v1/integrations/{integrationId}/contracts | Register a draft | Available |
GET /v1/integrations/{integrationId}/contracts/{contractVersionId} | Get one version | Available |
POST /v1/integrations/{integrationId}/contracts/{contractVersionId}/activate | Activate a version | Available |
GET /v1/integrations | List Integrations | Available |
GET /v1/incidents | List mode-scoped incidents | Available |
GET /v1/incidents/{incidentId} | Read mode-scoped incident evidence | Available |
GET /v1/repair-proposals/{proposalId} | Read mode-scoped proposal evidence | Available |
Integration inventory, observation evidence, mode-scoped incident and repair reads, usage, and the contract lifecycle are available now. Each operational read requires an explicit Sandbox or Live mode and its documented scope.
Other interfaces
- Node.js collector: the published SDK implements signing, bounded batching, and delivery rules.
- PHP collector and Laravel collector: published alpha packages that implement the same envelope and delivery contract.
- MCP server: read-only workspace access for AI clients through OAuth; a separate interface with separate credentials.
- Documentation: guides, concepts, and the collector reference.