Sync API¶

Import schemas from external sources: dbt, OpenAPI, and GraphQL.

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
}

Response¶

{
  "status": "success",
  "assets": { "created": 10, "updated": 5, "skipped": 2 },
  "contracts": { "published": 8 },
  "proposals": { "created": 2 },
  "registrations": { "created": 15 }
}

Legacy Sync¶

POST /api/v1/sync/dbt

Simple manifest upload (backwards compatibility).

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.

See dbt Integration Guide for full documentation.

OpenAPI Sync¶

Import API schemas from OpenAPI specifications.

Upload Spec¶

POST /api/v1/sync/openapi

Request Body¶

{
  "spec": { /* OpenAPI 3.x spec */ },
  "owner_team_id": "uuid",
  "prefix": "api",
  "auto_publish_contracts": true
}

Parameters¶

Parameter	Type	Default	Description
`spec`	object	required	OpenAPI 3.x specification
`owner_team_id`	UUID	required	Team to own created assets
`prefix`	string	`"api"`	Prefix for asset FQNs
`auto_publish_contracts`	boolean	`false`	Auto-publish contracts

Response¶

{
  "status": "success",
  "assets": { "created": 15, "updated": 3 },
  "contracts": { "published": 12 },
  "endpoints_processed": 18
}

Impact Analysis¶

POST /api/v1/sync/openapi/impact

Preview what would change.

Diff¶

POST /api/v1/sync/openapi/diff

CI/CD dry-run.

What Gets Synced¶

For each OpenAPI path/operation:

Creates an asset with FQN: {prefix}.{path}.{method}
Extracts request/response schemas
Converts to JSON Schema for contracts

Example:

# OpenAPI
paths:
  /users/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Becomes asset: api.users.{id}.get

GraphQL Sync¶

Import types from GraphQL schemas.

Upload Schema¶

POST /api/v1/sync/graphql

Request Body¶

{
  "schema": "type User { id: ID! name: String! }",
  "owner_team_id": "uuid",
  "prefix": "graphql",
  "auto_publish_contracts": true
}

Parameters¶

Parameter	Type	Default	Description
`schema`	string	required	GraphQL SDL
`owner_team_id`	UUID	required	Team to own created assets
`prefix`	string	`"graphql"`	Prefix for asset FQNs
`auto_publish_contracts`	boolean	`false`	Auto-publish contracts

Response¶

{
  "status": "success",
  "assets": { "created": 8, "updated": 2 },
  "contracts": { "published": 6 },
  "types_processed": 10
}

Impact Analysis¶

POST /api/v1/sync/graphql/impact

Preview what would change.

Diff¶

POST /api/v1/sync/graphql/diff

CI/CD dry-run.

What Gets Synced¶

For each GraphQL type:

Creates an asset with FQN: {prefix}.{TypeName}
Converts GraphQL type to JSON Schema
Handles: Object types, Input types, Enums

Example:

type User {
  id: ID!
  name: String!
  email: String
  role: Role!
}

enum Role {
  ADMIN
  USER
}

Becomes: - Asset: graphql.User with schema for User type - Asset: graphql.Role with enum schema

Conflict Modes¶

All sync endpoints support conflict_mode:

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