docs: Enhance Sonar API documentation with core concepts guides #67593
Conversation
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=80&v=4){kind=small}
Adds comprehensive documentation for key Airbyte Embedded concepts that were previously under-documented or missing entirely. Changes: - Add Authentication guide covering token types, security best practices, and implementation examples for Access Tokens, Scoped Tokens, and Widget Tokens - Add Workspace Management guide explaining multi-tenant architecture, workspace isolation, external ID best practices, and template tag filtering - Add Schema Discovery guide documenting catalog query endpoints, stream exploration, and programmatic data structure access - Enhance API README with better organization, Core Concepts section, and links to new documentation These changes address documentation gaps identified in the Sonar repository drift analysis, focusing on user-facing API features that lacked comprehensive usage guides. Related: Sonar documentation drift analysis 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
👋 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:
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
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: "- Streams: The tables/coll..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- A source is first configured"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Downloads all records every ..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Downloads only new/changed r..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Deduplication"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Source has many tables/colle..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Be patient - first discovery..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- User doesn't have permission..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Verify user permissions in t..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Source doesn't provide type ..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Review the source's native s..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Data sources are configured"]
[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: "1. Create a new workspace if o..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- UUID: `"550e8400-e29b-41d4-a..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Email addresses (not stable ..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Expires after a configurable..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- All workspaces in your organ..."]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- The external ID you assigned"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```json"]
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- [Scoped Token Generation](./..."]
| **Purpose:** Full administrative access to your organization | ||
|
|
||
| **Permissions:** | ||
| - Create and manage source templates |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Create and manage source tem..."]
| **Lifetime:** Long-lived (does not expire automatically) | ||
|
|
||
| **When to Use:** | ||
| - Backend server operations |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Backend server operations"]
| - Generating scoped tokens | ||
|
|
||
| **Security:** | ||
| - 🔐 **Never** expose to end-users |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- 🔐 Never expose to end-u..."]
| - ✅ **Use** only in trusted backend services | ||
|
|
||
| **How to Get:** | ||
| 1. Log in to [cloud.airbyte.com](https://cloud.airbyte.com) |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "1. Log in to [cloud.airbyte.co..."]
| **Purpose:** Limited access for individual end-users | ||
|
|
||
| **Permissions:** | ||
| - Configure sources in a single workspace |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Configure sources in a singl..."]
|
|
||
| ### [Schema Discovery](./schema-discovery.md) | ||
| Programmatically explore your customers' data structures: | ||
| - Discover available streams (tables/collections) |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Discover available streams (..."]
|
|
||
| ## API Guides | ||
|
|
||
| ### Setup & Configuration |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD022/blanks-around-headings Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "### Setup & Configuration"]
| ## API Guides | ||
|
|
||
| ### Setup & Configuration | ||
| - [Connection Templates](./connection-templates.md) - Configure destinations for your users |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- [Connection Templates](./con..."]
| - [Source Templates](./source-templates.md) - Define available data connectors | ||
| - [Configuring Sources](./configuring-sources.md) - Collect user credentials and create sources | ||
|
|
||
| ### Advanced Topics |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD022/blanks-around-headings Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "### Advanced Topics"]
| - [Configuring Sources](./configuring-sources.md) - Collect user credentials and create sources | ||
|
|
||
| ### Advanced Topics | ||
| - [Schema Discovery](./schema-discovery.md) - Explore data structures programmatically |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- [Schema Discovery](./schema-..."]
There was a problem hiding this comment.
Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit
markdownlint-fix
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
[markdownlint-fix] reported by reviewdog 🐶
| ## Core Concepts | ||
|
|
||
| ### [Authentication](./authentication.md) | ||
| Understand the different token types and how to securely authenticate your API calls: |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| Understand the different token types and how to securely authenticate your API calls: | |
| Understand the different token types and how to securely authenticate your API calls: |
|
|
||
| ### [Authentication](./authentication.md) | ||
| Understand the different token types and how to securely authenticate your API calls: | ||
| - **Access Tokens**: Organization-level administrative access |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| - **Access Tokens**: Organization-level administrative access | |
| - **Access Tokens**: Organization-level administrative access |
| - Security best practices and implementation examples | ||
|
|
||
| ### [Workspace Management](./workspace-management.md) | ||
| Learn how Airbyte Embedded creates isolated environments for each customer: |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| Learn how Airbyte Embedded creates isolated environments for each customer: | |
| Learn how Airbyte Embedded creates isolated environments for each customer: |
|
|
||
| ### [Workspace Management](./workspace-management.md) | ||
| Learn how Airbyte Embedded creates isolated environments for each customer: | ||
| - Multi-tenant architecture and data isolation |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| - Multi-tenant architecture and data isolation | |
| - Multi-tenant architecture and data isolation |
| - Template tag filtering for workspace-specific configurations | ||
|
|
||
| ### [Schema Discovery](./schema-discovery.md) | ||
| Programmatically explore your customers' data structures: |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| Programmatically explore your customers' data structures: | |
| Programmatically explore your customers' data structures: |
| ## API Reference | ||
|
|
||
| For complete authentication API documentation: | ||
| - [Scoped Token Generation](https://api.airbyte.ai/api/v1/docs#/Embedded/post_api_v1_embedded_scoped_token) |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| - [Scoped Token Generation](https://api.airbyte.ai/api/v1/docs#/Embedded/post_api_v1_embedded_scoped_token) | |
| - [Scoped Token Generation](https://api.airbyte.ai/api/v1/docs#/Embedded/post_api_v1_embedded_scoped_token) |
| ## Overview | ||
|
|
||
| Once a customer has configured a source, you can discover: | ||
| - **Streams**: The tables/collections/endpoints available in the source |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| - **Streams**: The tables/collections/endpoints available in the source | |
| - **Streams**: The tables/collections/endpoints available in the source |
| ### 1. Trigger Discovery | ||
|
|
||
| Discovery is the process of connecting to the source and retrieving its schema metadata. This happens automatically when: | ||
| - A source is first configured |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| - A source is first configured | |
| - A source is first configured |
| ``` | ||
|
|
||
| **Response:** | ||
| ```json |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| ```json | |
| ```json |
| ``` | ||
|
|
||
| **Response:** | ||
| ```json |
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
| ```json | |
| ```json |
1 participant
Summary
Enhances user-facing Sonar API documentation by adding comprehensive guides for key concepts that were previously under-documented or missing entirely. This PR addresses documentation gaps identified in the Sonar repository drift analysis.
Changes
Files Created
docs/ai-agents/embedded/api/authentication.md- Complete authentication guide covering:docs/ai-agents/embedded/api/workspace-management.md- Comprehensive workspace management guide covering:docs/ai-agents/embedded/api/schema-discovery.md- Schema discovery and catalog query guide covering:Files Updated
docs/ai-agents/embedded/api/README.md- Enhanced with:Documentation Scope
/docs/ai-agents/embedded/api/Related Work
This PR addresses user-facing documentation gaps from the Sonar repository's documentation drift analysis. The analysis identified several areas where public API features were functional but lacked comprehensive user documentation:
Review Checklist
Statistics
📚 Generated from Sonar documentation drift analysis
🤖 Generated with Claude Code
Co-Authored-By: Claude [email protected]