docs: Add comprehensive Sonar Embedded API documentation #67580

teallarson · 2025-10-08T23:15:18Z

Overview

This PR addresses critical documentation drift between the Sonar implementation and the Airbyte documentation repository. Based on a comprehensive drift analysis performed on 2025-10-08, this update adds missing API documentation for HIGH PRIORITY features that are fully implemented in Sonar but completely undocumented.

Reference: docs-drift-analysis-2025-10-08.md (in sonar repo)

Changes Summary

New Documentation Files (3)

workspaces.md - Workspace Management API
- List workspaces with cursor-based pagination
- Get, update, and delete workspaces
- Workspace statistics and sync operations
- Complete pagination guide and filtering examples
authentication.md - Complete Authentication Guide
- All three token types (Operator Bearer, Scoped, Widget)
- Region selection (US/EU)
- Template filtering via tags during token generation
- Token lifecycle management and security best practices
- 20+ code examples
tags.md - Template Tag Management
- Tag CRUD operations
- Tag selection modes (ANY vs ALL)
- Tagging source and connection templates
- Tier-based access control examples

Updated Documentation Files (3)

source-templates.md - Enhanced with stream management, PATCH endpoint, tag operations, source definition catalogs
connection-templates.md - Added sync_on_create, non_breaking_changes_preference, cron validation, PATCH endpoint, tag operations
configuring-sources.md - Added region selection, stream management, JMESPath querying, JSON Patch operations

Impact

25+ previously undocumented API endpoints now documented
~2,500 lines of documentation added
100+ code examples
12 HIGH PRIORITY documentation gaps addressed

Validation

All documentation validated against:

Sonar codebase at commit 350a75fe73
FastAPI route definitions
Pydantic schemas
Existing documentation style

Breaking Changes

None - Documentation only

This PR addresses critical documentation drift identified in the October 2025 drift analysis. The Sonar implementation has evolved significantly beyond the current documentation, and this update adds missing API documentation for HIGH PRIORITY features that are fully implemented but undocumented. ## New Documentation Files ### 1. workspaces.md - Workspace Management API Complete documentation for workspace management including: - List workspaces with cursor-based pagination - Get, update, and delete workspaces - Workspace statistics and sync operations - Filtering and pagination examples ### 2. authentication.md - Complete Authentication Guide Comprehensive authentication documentation covering: - All three token types (Operator Bearer, Scoped, Widget) - Region selection (US/EU) - Template filtering via tags - Token lifecycle management and security best practices - Common integration patterns with code examples ### 3. tags.md - Template Tag Management Central tag management documentation including: - Tag CRUD operations - Tag selection modes (ANY vs ALL) - Tagging source and connection templates - Filtering workflows and best practices - Tier-based access control examples ## Updated Documentation Files ### 4. source-templates.md - Enhanced Source Template Documentation Added missing functionality: - PATCH endpoint for template updates - Tag management operations - Stream management (discover, query, add, update, delete) - JMESPath catalog querying - Source definition catalog operations - JSON Patch examples ### 5. connection-templates.md - Complete Configuration Options Added missing functionality: - sync_on_create configuration option - non_breaking_changes_preference enum values and behavior - Cron expression validation endpoint - PATCH endpoint for updates - Tag management operations - Multi-tenant and compliance patterns ### 6. configuring-sources.md - Advanced Source Configuration Added missing functionality: - Region selection in token generation - Connection template tag filtering - Stream management operations - JMESPath catalog querying - JSON Patch operations for streams - Best practices and common workflows ## Impact This update documents 25+ previously undocumented API endpoints and addresses 12 HIGH PRIORITY documentation gaps: - Workspace Management API (6 endpoints) - Stream Operations (5 endpoints) - Template Tagging System (8 endpoints) - Authentication details (3 token types, regions, filtering) - Pagination documentation - Source Definition Catalogs (6 endpoints) ## Validation All documentation validated against: - Sonar codebase at commit 350a75fe73 - FastAPI route definitions - Pydantic schemas - Existing documentation style Reference: docs-drift-analysis-2025-10-08.md

github-actions · 2025-10-08T23:15:47Z

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

Helpful Resources

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

/format-fix - Fixes most formatting issues.
/bump-version - Bumps connector versions.
- You can specify a custom changelog by passing changelog. Example: /bump-version changelog="My cool update"
- Leaving the changelog arg blank will auto-populate the changelog from the PR title.
/run-cat-tests - Runs legacy CAT tests (Connector Acceptance Tests)
/build-connector-images - Builds and publishes a pre-release docker image for the modified connector(s).
JVM connectors:
- /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
  Example: /update-connector-cdk-version connector=destination-bigquery
- /bump-bulk-cdk-version type=patch changelog='foo' - Bump the Bulk CDK's version. type can be major/minor/patch.
Python connectors:
- /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
- /poe source example lock - Alias for /poe connector source-example lock.
- /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
- /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.

📝 Edit this welcome message.

github-actions

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

markdownlint

[markdownlint] _{reported by reviewdog 🐶}
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Use clear, descriptive names"]

airbyte/docs/ai-agents/embedded/api/connection-templates.md

Line 344 in c19651c

- Use clear, descriptive names

[markdownlint] _{reported by reviewdog 🐶}
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- any - Template must have a..."]

airbyte/docs/ai-agents/embedded/api/source-templates.md

Line 79 in c19651c

- `any` - Template must have at least one of the specified tags

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 21 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 34 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 46 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 59 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 84 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 125 in c19651c

#### Endpoint

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 127 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 131 in c19651c

#### Authentication

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 135 in c19651c

#### Request Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 142 in c19651c

#### Response Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 176 in c19651c

#### Endpoint

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 178 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 182 in c19651c

#### Authentication

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Body"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 192 in c19651c

#### Request Body

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 198 in c19651c

#### Request Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 209 in c19651c

#### Response Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 230 in c19651c

#### Endpoint

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 232 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 236 in c19651c

#### Authentication

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Path Parameters"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 240 in c19651c

#### Path Parameters

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 246 in c19651c

#### Request Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 253 in c19651c

#### Response Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Important Notes"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 262 in c19651c

#### Important Notes

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 274 in c19651c

#### Endpoint

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 276 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 280 in c19651c

#### Authentication

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Path Parameters"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 284 in c19651c

#### Path Parameters

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Body"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 290 in c19651c

#### Request Body

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 296 in c19651c

#### Request Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 307 in c19651c

#### Response Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 325 in c19651c

#### Endpoint

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 327 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 331 in c19651c

#### Authentication

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Path Parameters"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 335 in c19651c

#### Path Parameters

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 342 in c19651c

#### Request Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 349 in c19651c

#### Response Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 369 in c19651c

#### Endpoint

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 371 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 375 in c19651c

#### Authentication

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Path Parameters"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 379 in c19651c

#### Path Parameters

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Body"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 385 in c19651c

#### Request Body

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 391 in c19651c

#### Request Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 402 in c19651c

#### Response Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Endpoint"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 420 in c19651c

#### Endpoint

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 422 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Authentication"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 426 in c19651c

#### Authentication

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Path Parameters"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 430 in c19651c

#### Path Parameters

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Request Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 437 in c19651c

#### Request Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Response Example"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 444 in c19651c

#### Response Example

[markdownlint] _{reported by reviewdog 🐶}
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Source templates: Must h..."]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 479 in c19651c

- **Source templates**: Must have "pro-tier" OR "enterprise" tag (`any` mode)

[markdownlint] _{reported by reviewdog 🐶}
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 657 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 657 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 664 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 664 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]

airbyte/docs/ai-agents/embedded/api/tags.md

Line 673 in c19651c

```json

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 31 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 142 in c19651c

### Endpoint

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 144 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 154 in c19651c

### Request Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 161 in c19651c

### Response Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 178 in c19651c

### Endpoint

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 180 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Path Parameters"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 184 in c19651c

### Path Parameters

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 201 in c19651c

### Request Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 237 in c19651c

### Response Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 254 in c19651c

### Endpoint

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 256 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Path Parameters"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 260 in c19651c

### Path Parameters

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 266 in c19651c

### Request Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 273 in c19651c

### Response Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 292 in c19651c

### Endpoint

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 294 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 298 in c19651c

### Request Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 305 in c19651c

### Response Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Fields"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 315 in c19651c

### Response Fields

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 327 in c19651c

### Endpoint

[markdownlint] _{reported by reviewdog 🐶}
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 329 in c19651c

```

[markdownlint] _{reported by reviewdog 🐶}
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Keep your local workspace ca..."]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 336 in c19651c

- Keep your local workspace cache in sync with Airbyte Cloud

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 340 in c19651c

### Request Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 347 in c19651c

### Response Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Fields"]

airbyte/docs/ai-agents/embedded/api/workspaces.md

Line 360 in c19651c

### Response Fields

github-actions · 2025-10-08T23:23:51Z

Deploy preview for airbyte-docs ready!

✅ Preview
https://airbyte-docs-m9ro3gr66-airbyte-growth.vercel.app

Built with commit 019d933.
This pull request is being automatically deployed with vercel-action

teallarson · 2025-10-10T19:04:48Z

Updated the agents to run markdown linting and vale (writing style) linting.

Going to have them re-review what they wrote here (not re-run the full analysis).

- Add language specifiers to all code blocks - Fix spacing around code blocks and lists - Convert headings to sentence-case per style guide - Fix terminology (e.g. to for example, Cors to CORS, saas to SaaS) - Add 35 technical terms to Vale vocabulary - Update markdownlint config to allow duplicate headings with siblings_only Resolves 148 total linting errors (114 markdownlint + 34 vale)

teallarson · 2025-10-10T19:44:56Z

@tgonzalezc5 we can decide what to do with this PR, but it contains all of the docs our agents wrote last week that are missing in the embedded docs! I think it's probably worth a review and ship, but not sure how it might conflict with anything you had in flight.

They seem mostly correct (I'm least sure about the schema/catalog things) but should probably be reviewed as though some pretty junior external contractor wrote them IMO.

Would love any feedback you have on how it did, too. We can tweak and improve the agents!

tgonzalezc5

This looks great.

girarda

a few things are off. I'll review and fix before we merge

github-actions · 2025-10-13T19:10:26Z

docs/ai-agents/embedded/api/workspaces.md

+| `inactive_count` | integer | Number of workspaces with status `inactive` |
+| `total_count` | integer | Total number of workspaces |
+
+### Response fields


[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response fields"]

github-actions

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

vale

docs/ai-agents/embedded/api/tags.md|666 col 5| [Google.Headings] 'Workflow 3: feature staging' should use sentence-style capitalization.
docs/ai-agents/embedded/api/tags.md|735 col 1| [Google.Colons] ': A' should be in lowercase.
docs/ai-agents/embedded/api/tags.md|737 col 1| [Google.Colons] ': V' should be in lowercase.
docs/ai-agents/embedded/api/tags.md|748 col 1| [Google.Colons] ': A' should be in lowercase.
docs/ai-agents/embedded/api/tags.md|750 col 1| [Google.Colons] ': L' should be in lowercase.
docs/ai-agents/embedded/api/tags.md|767 col 1| [Google.Colons] ': T' should be in lowercase.
docs/ai-agents/embedded/api/tags.md|769 col 1| [Google.Colons] ': U' should be in lowercase.

github-actions · 2025-10-13T19:11:22Z

docs/ai-agents/embedded/api/source-templates.md

 ```

-Sources created from a deleted Source Template will stop showing up in the Widget.
+When a source template is updated, all existing sources created from it will also be updated.


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.Will] Avoid using 'will'.

github-actions · 2025-10-13T19:11:22Z

docs/ai-agents/embedded/api/source-templates.md

+
+```
+
+Sources created from a deleted source template will stop showing up in the widget.


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.Will] Avoid using 'will'.

github-actions · 2025-10-13T19:11:22Z

docs/ai-agents/embedded/api/configuring-sources.md

+
+- `workspace_name` is a unique identifier within your organization for each customer's tenant
+- `region_id` (optional) is the region where the workspace should be created:
+  - US region: `645a183f-b12b-4c6e-8ad3-99e165603450` (default)


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.We] Try to avoid using first-person plural like 'US'.

github-actions · 2025-10-13T19:11:22Z

docs/ai-agents/embedded/api/configuring-sources.md

+For widget integration, see [Authentication - Widget Token](./authentication.md#widget-token).

-# Creating a Source
+## Creating a Source


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.Headings] 'Creating a Source' should use sentence-style capitalization.

github-actions · 2025-10-13T19:11:22Z

docs/ai-agents/embedded/api/configuring-sources.md

+
+### Stream selection modes
+
+There are three stream selection modes available:


🚫 [vale] _{reported by reviewdog 🐶}
[write-good.ThereIs] Don't start a sentence with 'There are'.

github-actions · 2025-10-13T19:11:24Z

docs/ai-agents/embedded/api/workspaces.md

+
+```
+
+**Cause:** Invalid request parameters


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.Colons] ': I' should be in lowercase.

github-actions · 2025-10-13T19:11:25Z

docs/ai-agents/embedded/api/workspaces.md

+
+**Cause:** Invalid request parameters
+
+**Solution:** Check that all parameters match the expected format and values


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.Colons] ': C' should be in lowercase.

github-actions · 2025-10-13T19:11:25Z

docs/ai-agents/embedded/api/tags.md

@@ -0,0 +1,845 @@
+# Template Tags


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.Headings] 'Template Tags' should use sentence-style capitalization.

github-actions · 2025-10-13T19:11:25Z

docs/ai-agents/embedded/api/tags.md

+
+- Deleting a tag removes all associations with source and connection templates
+- This operation cannot be undone
+- Templates will remain but will no longer have this tag


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.Will] Avoid using 'will'.

github-actions · 2025-10-13T19:11:25Z

docs/ai-agents/embedded/api/tags.md

+
+- Deleting a tag removes all associations with source and connection templates
+- This operation cannot be undone
+- Templates will remain but will no longer have this tag


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.Will] Avoid using 'will'.

github-actions bot reviewed Oct 8, 2025

View reviewed changes

teallarson requested a review from tgonzalezc5 October 10, 2025 19:42

tgonzalezc5 approved these changes Oct 13, 2025

View reviewed changes

girarda requested changes Oct 13, 2025

View reviewed changes

girarda added 7 commits October 13, 2025 11:46

update authentication docs

f45fc80

update configuring sources

6978bcd

update connection templates doc

512cef4

remove some more docs

029c977

update tags docs

6fc908b

update workspaces docs

5afbe19

add notes on stream selection

e322e83

girarda self-requested a review October 13, 2025 19:08

girarda approved these changes Oct 13, 2025

View reviewed changes

Merge branch 'master' into docs/sonar-api-documentation-update

019d933

github-actions bot reviewed Oct 13, 2025

View reviewed changes

girarda merged commit b50994c into master Oct 13, 2025
34 checks passed

girarda deleted the docs/sonar-api-documentation-update branch October 13, 2025 19:41


		```

		Sources created from a deleted source template will stop showing up in the widget.


		### Stream selection modes

		There are three stream selection modes available:


		Cause: Invalid request parameters

		Solution: Check that all parameters match the expected format and values

docs: Add comprehensive Sonar Embedded API documentation #67580

docs: Add comprehensive Sonar Embedded API documentation #67580

Conversation

teallarson commented Oct 8, 2025

Overview

Changes Summary

New Documentation Files (3)

Updated Documentation Files (3)

Impact

Validation

Breaking Changes

Uh oh!

github-actions bot commented Oct 8, 2025

👋 Greetings, Airbyte Team Member!

Helpful Resources

PR Slash Commands

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

teallarson commented Oct 10, 2025

Uh oh!

teallarson commented Oct 10, 2025

Uh oh!

tgonzalezc5 left a comment

Choose a reason for hiding this comment

Uh oh!

girarda left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Oct 8, 2025 •

edited

Loading