Skip to content

Conversation

devin-ai-integration[bot]
Copy link
Contributor

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

  1. docs/ai-agents/embedded/api/authentication.md - Complete authentication guide covering:

    • Three token types: Access Tokens, Scoped Tokens, and Widget Tokens
    • Detailed permissions and security implications for each token type
    • Authentication flows for backend-to-backend and customer-facing scenarios
    • Implementation examples in Node.js with token caching and refresh logic
    • Security best practices and troubleshooting guidance
  2. docs/ai-agents/embedded/api/workspace-management.md - Comprehensive workspace management guide covering:

    • Multi-tenant architecture and data isolation with Row Level Security (RLS)
    • Automatic workspace creation and external ID best practices
    • Template tag filtering for workspace-specific configurations
    • Viewing and managing customer workspaces
    • Security, scalability, and organization best practices
    • Troubleshooting common workspace issues
  3. docs/ai-agents/embedded/api/schema-discovery.md - Schema discovery and catalog query guide covering:

    • Discovery process and catalog querying
    • Stream and field schema exploration
    • JSON Schema format explanation with data types and formats
    • Sync modes (full refresh vs. incremental) and primary keys
    • Use cases: dynamic UIs, data validation, schema monitoring, AI/ML features
    • Caching, error handling, and performance best practices

Files Updated

  1. docs/ai-agents/embedded/api/README.md - Enhanced with:
    • Renamed "Implementation Steps" to "Quick Start" for clarity
    • New "Core Concepts" section with links to the three new guides
    • Better organization of API Guides into Setup & Configuration and Advanced Topics
    • Added "Need Help?" section with support resources

Documentation Scope

  • Target: User-facing Sonar API documentation in /docs/ai-agents/embedded/api/
  • Audience: Developers building with Airbyte Embedded
  • Focus: Public API features that lacked comprehensive usage guides

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:

  • Authentication: Token types were mentioned in API docs but lacked usage guides and security best practices
  • Workspace Management: Workspaces were mentioned but multi-tenant architecture wasn't clearly explained
  • Schema Discovery: Catalog query endpoints existed but lacked usage examples and use cases

Review Checklist

  • Documentation is clear and accurate
  • Code examples are correct (JavaScript/Node.js)
  • Cross-references and internal links work correctly
  • Follows existing documentation style and structure
  • API endpoints and parameters match current OpenAPI spec
  • Security best practices are clearly highlighted
  • Examples include error handling and edge cases

Statistics

  • Total Files Changed: 4 (3 created, 1 updated)
  • Lines Added: ~1,225
  • Documentation Sections: 3 major new guides + 1 enhancement
  • Code Examples: 15+ implementation examples in JavaScript/Node.js

📚 Generated from Sonar documentation drift analysis
🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]

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]>
Copy link
Contributor

github-actions bot commented Oct 9, 2025

👋 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.

Copy link
Contributor

@github-actions github-actions bot left a 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: "- Streams: The tables/coll..."]

- **Streams**: The tables/collections/endpoints available in the source


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- A source is first configured"]

- 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 ..."]

- Downloads all records every sync


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Downloads only new/changed r..."]

- Downloads only new/changed records


[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..."]

- Source has many tables/collections


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Be patient - first discovery..."]

- Be patient - first discovery can take several minutes


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- User doesn't have permission..."]

- User doesn't have permissions in the source system


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Verify user permissions in t..."]

- Verify user permissions in the source system


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Source doesn't provide type ..."]

- Source doesn't provide type information


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Review the source's native s..."]

- Review the source's native schema


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Data sources are configured"]

- 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..."]

1. Create a new workspace if one doesn't exist for `external_id: customer-unique-id-123`


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- UUID: `"550e8400-e29b-41d4-a..."]

- UUID: `"550e8400-e29b-41d4-a716-446655440000"`


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Email addresses (not stable ..."]

- Email addresses (not stable if customer changes email)


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Expires after a configurable..."]

- Expires after a configurable time period


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- All workspaces in your organ..."]

- All workspaces in your organization


[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- The external ID you assigned"]

- 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](./..."]

- [Scoped Token Generation](./configuring-sources.md#generating-scoped-tokens)

**Purpose:** Full administrative access to your organization

**Permissions:**
- Create and manage source templates
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- Discover available streams (..."]


## API Guides

### Setup & Configuration
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[markdownlint] reported by reviewdog 🐶
MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- [Schema Discovery](./schema-..."]

Copy link
Contributor

@github-actions github-actions bot left a 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-fix

[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶

- Downloads all records every sync


[markdownlint-fix] reported by reviewdog 🐶

- Downloads only new/changed records


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶

- Source has many tables/collections


[markdownlint-fix] reported by reviewdog 🐶

- Be patient - first discovery can take several minutes


[markdownlint-fix] reported by reviewdog 🐶

- User doesn't have permissions in the source system


[markdownlint-fix] reported by reviewdog 🐶

- Verify user permissions in the source system


[markdownlint-fix] reported by reviewdog 🐶

- Source doesn't provide type information


[markdownlint-fix] reported by reviewdog 🐶

- Review the source's native schema


[markdownlint-fix] reported by reviewdog 🐶

- Data sources are configured


[markdownlint-fix] reported by reviewdog 🐶

1. Create a new workspace if one doesn't exist for `external_id: customer-unique-id-123`


[markdownlint-fix] reported by reviewdog 🐶

- UUID: `"550e8400-e29b-41d4-a716-446655440000"`


[markdownlint-fix] reported by reviewdog 🐶

- Email addresses (not stable if customer changes email)


[markdownlint-fix] reported by reviewdog 🐶

- Expires after a configurable time period


[markdownlint-fix] reported by reviewdog 🐶

- All workspaces in your organization


[markdownlint-fix] reported by reviewdog 🐶

- The external ID you assigned


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶

- [Scoped Token Generation](./configuring-sources.md#generating-scoped-tokens)

## Core Concepts

### [Authentication](./authentication.md)
Understand the different token types and how to securely authenticate your API calls:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[markdownlint-fix] reported by reviewdog 🐶

Suggested change
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[markdownlint-fix] reported by reviewdog 🐶

Suggested change
- **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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[markdownlint-fix] reported by reviewdog 🐶

Suggested change
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[markdownlint-fix] reported by reviewdog 🐶

Suggested change
- 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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[markdownlint-fix] reported by reviewdog 🐶

Suggested change
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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[markdownlint-fix] reported by reviewdog 🐶

Suggested change
- [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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[markdownlint-fix] reported by reviewdog 🐶

Suggested change
- **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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[markdownlint-fix] reported by reviewdog 🐶

Suggested change
- A source is first configured
- A source is first configured

```

**Response:**
```json
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[markdownlint-fix] reported by reviewdog 🐶

Suggested change
```json
```json

```

**Response:**
```json
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[markdownlint-fix] reported by reviewdog 🐶

Suggested change
```json
```json

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Waiting Eng Team

Development

Successfully merging this pull request may close these issues.

1 participant