mirror of synced 2025-12-20 18:39:31 -05:00

Files

Teal Larson b50994c6f3 docs: Add comprehensive Sonar Embedded API documentation (#67580 )

## 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)

1. **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

2. **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

3. **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)

4. **source-templates.md** - Enhanced with stream management, PATCH
endpoint, tag operations, source definition catalogs

5. **connection-templates.md** - Added sync_on_create,
non_breaking_changes_preference, cron validation, PATCH endpoint, tag
operations

6. **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

---------

Co-authored-by: Alexandre Girard <alexandre@airbyte.io>

2025-10-13 12:41:54 -07:00

4.1 KiB

Raw Permalink Blame History

products

products
embedded

Source Templates

A source template controls which connectors appear in the Embedded widget and how their config screens look. When a customer opens the widget, only the sources backed by a template are selectable, so you can pre-set sensible defaults or restrict advanced settings.

The Airbyte platform comes with ready-to-use templates. You can also create templates specific to your organization if you need access to more integrations or if you want different default values.

Creating source templates

Here is an example request to create a new template using only default values:

curl https://api.airbyte.ai/api/v1/integrations/templates/sources \

  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  --data-raw '{

    "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
    "actor_definition_id": "45b7d7e6-d7d5-4f31-8c1a-9fd96ce6ee35",
    "partial_default_config": {}
  }'

You can find the actor definition ID from the Connector Registry.

The partial_default_config is a JSON object representing keys from the connector spec for which you want to set default values so your users don't need to set them up themselves.

Optional: add tags during creation

You can also add tags to organize and filter templates:

curl https://api.airbyte.ai/api/v1/integrations/templates/sources \

  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  --data-raw '{

    "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
    "actor_definition_id": "45b7d7e6-d7d5-4f31-8c1a-9fd96ce6ee35",
    "partial_default_config": {},
    "tags": ["crm", "pro-tier"]
  }'

See Template Tags for more information on organizing templates with tags.

Updating source templates

You can update an existing source template using the PATCH endpoint:

curl -X PATCH https://api.airbyte.ai/api/v1/integrations/templates/sources/{id} \

  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  --data-raw '{

    "partial_default_config": {
      "api_key": "new_default_value"
    }
  }'

When a source template is updated, all existing sources created from it will also be updated.

Listing templates

The List Source Templates endpoint lists both the templates you created, as well as standard templates that are available to everyone using the platform.

Filter by tags

You can filter source templates by tags:

curl 'https://api.airbyte.ai/api/v1/integrations/templates/sources?tags=crm&tags=sales&tags_mode=any' \

  -H 'Authorization: Bearer <token>'

Tag Selection Modes:

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

Deleting templates

You can delete source templates by submitting a DELETE request to the API:

curl -X DELETE 'https://api.airbyte.ai/api/v1/integrations/templates/sources/{id}' \

  -H 'Authorization: Bearer <token>'

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

Managing template tags

Add tag to source template

curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/sources/{id}/tags \

  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{

    "tag": "pro-tier"
  }'

Remove tag from source template

curl -X DELETE https://api.airbyte.ai/api/v1/integrations/templates/sources/{id}/tags/{tag_name} \

  -H 'Authorization: Bearer <token>'

For complete tag management documentation, see Template Tags.

Template Tags - Organize and filter templates with tags
Configuring Sources - Create sources from templates
Connection Templates - Configure sync behavior
Authentication - Generate tokens for API access

4.1 KiB Raw Permalink Blame History