Sync API¶

Import schemas from external sources. Each sync adapter normalizes its source format to JSON Schema contracts that flow through the same contract engine.

dbt Sync¶

Upload Manifest¶

POST /api/v1/sync/dbt/upload

Full manifest sync with automation options.

Request Body¶

{
  "manifest": { /* manifest.json contents */ },
  "owner_team_id": "uuid",
  "conflict_mode": "overwrite",
  "auto_publish_contracts": true,
  "auto_create_proposals": true,
  "auto_register_consumers": true,
  "infer_consumers_from_refs": true,
  "auto_delete": false
}

Parameter	Type	Default	Description
`manifest`	object	required	Contents of manifest.json
`owner_team_id`	UUID	required	Default team for new assets
`conflict_mode`	string	`"ignore"`	How to handle existing assets
`auto_publish_contracts`	boolean	`false`	Auto-publish contracts
`auto_create_proposals`	boolean	`false`	Create proposals for breaking changes
`auto_register_consumers`	boolean	`false`	Register consumers from meta
`infer_consumers_from_refs`	boolean	`false`	Infer consumers from ref()
`auto_delete`	boolean	`false`	Soft-delete dbt-managed assets missing from manifest

Response¶

Returns 200 when all operations succeed, or 207 Multi-Status when any contract publishes or consumer registrations fail (partial success).

{
  "status": "success",
  "assets": { "created": 10, "updated": 5, "skipped": 2, "deleted": 1, "deleted_fqns": ["db.schema.old_model"] },
  "contracts": { "published": 8 },
  "proposals": { "created": 2 },
  "registrations": { "created": 15 },
  "contract_warnings": [],
  "registration_warnings": []
}

Status	`status` field	Meaning
200	`"success"`	All operations completed successfully
207	`"partial_success"`	Some contract publishes or registrations failed; check `contract_warnings` and `registration_warnings`

Legacy Sync¶

POST /api/v1/sync/dbt

Simple manifest upload (backwards compatibility). Consider using /upload instead.

Impact Analysis¶

POST /api/v1/sync/dbt/impact

Preview impact without applying changes.

Diff¶

POST /api/v1/sync/dbt/diff

Dry-run for CI/CD pipelines. Detects: - New models (not in Tessera) - Modified models (schema changes) - Deleted models (in Tessera but missing from manifest) - Breaking changes

Response includes summary.deleted count and models with change_type: "deleted".

See dbt Integration Guide for full documentation.

OpenAPI Sync¶

Import API schemas from OpenAPI specifications.

Import Spec¶

POST /api/v1/sync/openapi

Request Body¶

{
  "spec": { /* OpenAPI 3.x spec */ },
  "owner_team_id": "uuid",
  "environment": "production",
  "auto_publish_contracts": true,
  "dry_run": false,
  "default_guarantees": {
    "freshness": { "max_staleness_minutes": 60 }
  }
}

Parameter	Type	Default	Description
`spec`	object	required	OpenAPI 3.x specification
`owner_team_id`	UUID	required	Team to own created assets
`environment`	string	`"production"`	Environment for assets
`auto_publish_contracts`	boolean	`true`	Auto-publish contracts for new assets
`dry_run`	boolean	`false`	Preview changes without persisting
`default_guarantees`	object	`null`	Default guarantees to apply to all endpoints

Response¶

{
  "api_title": "Users API",
  "api_version": "1.0.0",
  "endpoints_found": 18,
  "assets_created": 15,
  "assets_updated": 3,
  "assets_skipped": 0,
  "contracts_published": 15,
  "endpoints": [
    {
      "fqn": "api.users_api.get_users_id",
      "path": "/users/{id}",
      "method": "GET",
      "action": "created",
      "asset_id": "uuid",
      "contract_id": "uuid"
    }
  ],
  "parse_errors": []
}

Impact Analysis¶

POST /api/v1/sync/openapi/impact

Check what would change against existing contracts.

Request Body¶

{
  "spec": { /* OpenAPI 3.x spec */ },
  "environment": "production"
}

Response¶

{
  "status": "success",
  "api_title": "Users API",
  "api_version": "1.0.0",
  "total_endpoints": 10,
  "endpoints_with_contracts": 8,
  "breaking_changes_count": 2,
  "results": [
    {
      "fqn": "api.users_api.get_users_id",
      "path": "/users/{id}",
      "method": "GET",
      "has_contract": true,
      "safe_to_publish": false,
      "change_type": "major",
      "breaking_changes": [
        { "type": "property_removed", "path": "$.response.email" }
      ]
    }
  ],
  "parse_errors": []
}

Diff (CI/CD)¶

POST /api/v1/sync/openapi/diff

Dry-run for CI pipelines with blocking support.

Request Body¶

{
  "spec": { /* OpenAPI 3.x spec */ },
  "environment": "production",
  "fail_on_breaking": true
}

Response¶

{
  "status": "breaking_changes_detected",
  "api_title": "Users API",
  "api_version": "1.0.0",
  "summary": { "new": 2, "modified": 3, "unchanged": 5, "breaking": 1 },
  "blocking": true,
  "endpoints": [
    {
      "fqn": "api.users_api.get_users_id",
      "path": "/users/{id}",
      "method": "GET",
      "change_type": "modified",
      "has_schema": true,
      "schema_change_type": "breaking",
      "breaking_changes": []
    }
  ],
  "parse_errors": []
}

What Gets Synced¶

For each OpenAPI path/operation:

Creates an asset with FQN: api.<api_title>.<method>_<path>
Extracts request/response schemas
Converts to JSON Schema for contracts

Example:

# OpenAPI spec with title "Users API"
paths:
  /users/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Becomes asset: api.users_api.get_users_id

GraphQL Sync¶

Import operations from GraphQL introspection responses.

Import Schema¶

POST /api/v1/sync/graphql

Request Body¶

{
  "introspection": { /* GraphQL introspection response */ },
  "schema_name": "Users API",
  "owner_team_id": "uuid",
  "environment": "production",
  "auto_publish_contracts": true,
  "dry_run": false,
  "default_guarantees": null
}

Parameter	Type	Default	Description
`introspection`	object	required	GraphQL introspection response (`__schema` or `data.__schema`)
`schema_name`	string	`"GraphQL API"`	Name for the schema (used in FQN generation)
`owner_team_id`	UUID	required	Team to own created assets
`environment`	string	`"production"`	Environment for assets
`auto_publish_contracts`	boolean	`true`	Auto-publish contracts for new assets
`dry_run`	boolean	`false`	Preview changes without persisting
`default_guarantees`	object	`null`	Default guarantees to apply to all operations

To get an introspection response, run the standard introspection query:

query IntrospectionQuery {
  __schema {
    queryType { name }
    mutationType { name }
    types {
      kind name description
      fields { name description args { name type { ...TypeRef } } type { ...TypeRef } }
      inputFields { name type { ...TypeRef } }
      enumValues { name description }
    }
  }
}

fragment TypeRef on __Type {
  kind name
  ofType { kind name ofType { kind name ofType { kind name } } }
}

Response¶

{
  "schema_name": "Users API",
  "operations_found": 10,
  "assets_created": 8,
  "assets_updated": 2,
  "assets_skipped": 0,
  "contracts_published": 8,
  "operations": [
    {
      "fqn": "graphql.users_api.query_get_user",
      "operation_name": "getUser",
      "operation_type": "query",
      "action": "created",
      "asset_id": "uuid",
      "contract_id": "uuid"
    }
  ],
  "parse_errors": []
}

Impact Analysis¶

POST /api/v1/sync/graphql/impact

Check what would change against existing contracts.

Request Body¶

{
  "introspection": { /* GraphQL introspection response */ },
  "schema_name": "Users API",
  "environment": "production"
}

Response¶

{
  "status": "success",
  "schema_name": "Users API",
  "total_operations": 10,
  "operations_with_contracts": 8,
  "breaking_changes_count": 0,
  "results": [
    {
      "fqn": "graphql.users_api.query_get_user",
      "operation_name": "getUser",
      "operation_type": "query",
      "has_contract": true,
      "safe_to_publish": true,
      "change_type": "none",
      "breaking_changes": []
    }
  ],
  "parse_errors": []
}

Diff (CI/CD)¶

POST /api/v1/sync/graphql/diff

Dry-run for CI pipelines with blocking support.

Request Body¶

{
  "introspection": { /* GraphQL introspection response */ },
  "schema_name": "Users API",
  "environment": "production",
  "fail_on_breaking": true
}

Response¶

{
  "status": "clean",
  "schema_name": "Users API",
  "summary": { "new": 0, "modified": 1, "unchanged": 9, "breaking": 0 },
  "blocking": false,
  "operations": [
    {
      "fqn": "graphql.users_api.query_get_user",
      "operation_name": "getUser",
      "operation_type": "query",
      "change_type": "unchanged",
      "has_schema": true,
      "schema_change_type": "none",
      "breaking_changes": []
    }
  ],
  "parse_errors": []
}

What Gets Synced¶

For each GraphQL query/mutation:

Creates an asset with FQN: graphql.<schema_name>.<type>_<operation_name>
Extracts argument and return type schemas
Converts to JSON Schema for contracts

Example:

# Schema named "Users API"
type Query {
  getUser(id: ID!): User
  listUsers(limit: Int): [User!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

Becomes: - graphql.users_api.query_get_user - graphql.users_api.query_list_users - graphql.users_api.mutation_create_user

gRPC Sync¶

Import assets and contracts from Protocol Buffer (.proto) files. Each RPC method becomes an asset with resource_type=grpc_service, and the request/response message types are converted to JSON Schema contracts.

Import from Proto File¶

POST /api/v1/sync/grpc

Parse a proto3 file and create assets for each RPC method. Requires admin scope.

Request Body¶

{
  "proto_content": "syntax = \"proto3\";\npackage orders;\n...",
  "owner_team_id": "uuid",
  "publish_contracts": true,
  "dry_run": false
}

Response¶

{
  "assets_created": 3,
  "assets_updated": 1,
  "contracts_published": 3,
  "errors": []
}

Impact Analysis¶

POST /api/v1/sync/grpc/impact

Analyze what would break if a proto file is applied. Returns per-method impact including breaking changes.

Request Body¶

{
  "proto_content": "syntax = \"proto3\";\n...",
  "owner_team_id": "uuid"
}

CI Diff (Dry Run)¶

POST /api/v1/sync/grpc/diff

Preview what would change if this .proto file is applied. Use in PR checks to detect breaking changes before merging.

Request Body¶

{
  "proto_content": "syntax = \"proto3\";\n...",
  "owner_team_id": "uuid",
  "fail_on_breaking": true
}

Response¶

{
  "status": "breaking_changes_detected",
  "package": "orders",
  "summary": {"new": 0, "modified": 2, "unchanged": 1, "breaking": 1},
  "blocking": true,
  "methods": [
    {
      "fqn": "grpc.orders.OrderService.CreateOrder",
      "status": "breaking",
      "change_type": "major",
      "breaking_changes": [
        {"type": "property_removed", "path": "properties.old_field", "message": "Field removed"}
      ]
    }
  ],
  "parse_errors": []
}

What Gets Synced (gRPC)¶

For each RPC method in a proto service:

Creates an asset with FQN: grpc.<package>.<ServiceName>.<MethodName>
Extracts request and response message types
Converts to JSON Schema for contracts

Conflict Modes¶

The dbt sync endpoints support conflict_mode:

Mode	Behavior
`ignore`	Skip existing assets (default, safe)
`overwrite`	Update existing assets
`fail`	Error if any asset exists

OpenAPI and GraphQL endpoints handle existing assets by updating metadata (no skip/fail modes).