-
Notifications
You must be signed in to change notification settings - Fork 4.8k
docs: Add comprehensive Sonar Embedded API documentation #67580
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Conversation
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
👋 Greetings, Airbyte Team Member!Here are some helpful tips and reminders for your convenience. Helpful Resources
PR Slash CommandsAirbyte Maintainers (that's you!) can execute the following slash commands on your PR:
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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"]
- 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..."]
- `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: "```"]
``` |
[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
``` |
[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
``` |
[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
``` |
[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
``` |
[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: "```"]
``` |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]
### Endpoint |
[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
``` |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]
### Request Example |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]
### Response Example |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]
### Endpoint |
[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
``` |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Path Parameters"]
### Path Parameters |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]
### Request Example |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]
### Response Example |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]
### Endpoint |
[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
``` |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Path Parameters"]
### Path Parameters |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]
### Request Example |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]
### Response Example |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]
### Endpoint |
[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
``` |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Request Example"]
### Request Example |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]
### Response Example |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Fields"]
### Response Fields |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Endpoint"]
### Endpoint |
[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
``` |
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Keep your local workspace ca..."]
- 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"]
### Request Example |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Example"]
### Response Example |
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Response Fields"]
### Response Fields |
Deploy preview for airbyte-docs ready! ✅ Preview Built with commit ca11832. |
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)
@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! |
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
authentication.md - Complete Authentication Guide
tags.md - Template Tag Management
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
Validation
All documentation validated against:
Breaking Changes
None - Documentation only