Proposals API¶

Manage breaking change proposals in Tessera.

List Proposals¶

GET /api/v1/proposals

Query Parameters¶

Parameter	Type	Description
`asset_id`	uuid	Filter by asset
`status`	string	Filter by status (pending, approved, published, rejected)
`page`	int	Page number
`page_size`	int	Results per page

Response¶

{
  "results": [
    {
      "id": "proposal-uuid",
      "asset_id": "asset-uuid",
      "asset_fqn": "warehouse.analytics.users",
      "status": "pending",
      "change_type": "major",
      "breaking_changes_count": 2,
      "total_consumers": 3,
      "acknowledgment_count": 1,
      "proposed_at": "2025-01-15T10:00:00Z",
      "proposed_by": "team-uuid"
    }
  ]
}

Get Proposal¶

GET /api/v1/proposals/{proposal_id}

Response¶

{
  "id": "proposal-uuid",
  "asset_id": "asset-uuid",
  "asset_fqn": "warehouse.analytics.users",
  "status": "pending",
  "change_type": "major",
  "proposed_schema": {...},
  "breaking_changes": [
    {
      "type": "property_removed",
      "path": "$.properties.email",
      "description": "Property 'email' was removed"
    }
  ],
  "consumers": [
    {
      "team_id": "team-uuid",
      "team_name": "Analytics",
      "acknowledged": true,
      "acknowledged_at": "2025-01-16T10:00:00Z",
      "notes": "Updated our dashboards"
    },
    {
      "team_id": "team-uuid-2",
      "team_name": "Finance",
      "acknowledged": false
    }
  ],
  "proposed_at": "2025-01-15T10:00:00Z",
  "proposed_by": "team-uuid"
}

Acknowledge Proposal¶

POST /api/v1/proposals/{proposal_id}/acknowledge

Acknowledge that your team is ready for the breaking change.

Request Body¶

{
  "notes": "We've updated our dashboards to handle this change"
}

Response¶

{
  "acknowledged": true,
  "acknowledged_at": "2025-01-16T10:00:00Z",
  "remaining_consumers": 1
}

Get Proposal Status¶

GET /api/v1/proposals/{proposal_id}/status

Quick check of acknowledgment progress.

Response¶

{
  "status": "pending",
  "total_consumers": 3,
  "acknowledged": 2,
  "remaining": 1,
  "can_publish": false
}

Force Publish¶

POST /api/v1/proposals/{proposal_id}/force

Publish without waiting for all acknowledgments (admin only).

Request Body¶

{
  "reason": "Critical security fix, cannot wait for all acknowledgments"
}

Response¶

Returns the updated proposal with status force_published.

Audit Trail

Force publishing is logged with the reason. Use sparingly.

Publish Proposal¶

POST /api/v1/proposals/{proposal_id}/publish

Publish a proposal after all consumers have acknowledged.

Response¶

Returns the published contract details.

Withdraw Proposal¶

POST /api/v1/proposals/{proposal_id}/withdraw

Withdraw a pending proposal (producer only).

Request Body¶

{
  "reason": "Decided to take a different approach"
}

Response¶

Returns the updated proposal with status withdrawn.