Discovery

Discovery is how SixDegree automatically learns about your infrastructure. When you connect a service like GitHub or Argo CD, the molecule discovers what exists — repositories, deployments, users — and builds your ontology without manual data entry.

How It Works

1. You configure a molecule with credentials and settings
2. The molecule scans the external service for resources
3. Entities and relationships are streamed back to the platform
4. The ontology is updated with new, changed, or removed resources

Discovery is incremental — after the initial full scan, only new or changed resources are processed each time, keeping sync fast even for large environments.

Discovery Modes

Molecules support different discovery modes depending on the service they integrate with:

Polling

Interval-based discovery that runs on a schedule. The molecule periodically scans the external service for changes.

• Default for most molecules
• Configurable interval (e.g., every 15 minutes, hourly, daily)
• Good for services without webhook support

Webhook

Event-driven discovery triggered by real-time events from the external service. When something changes (a new repo is created, a deployment completes), the service notifies SixDegree immediately.

• Near real-time updates
• Lower API usage than polling
• Requires the external service to support webhooks

Both

Some molecules support both polling and webhooks simultaneously. Webhooks handle real-time updates while polling acts as a safety net to catch anything missed.

Running Discovery

Manual

Run discovery on demand when you need immediate updates:

1. Go to Integrations
2. Find your integration
3. Click Run Discovery

This triggers a full discovery cycle regardless of the scheduled interval.

Scheduled

Discovery runs automatically based on the molecule's configured schedule. You can adjust the interval per molecule when configuring it in your environment.

Via API

Trigger discovery programmatically using the API:

curl -X POST https://api.sixdegree.ai/environments/{env-id}/discovery/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"moleculeId": "github"}'

Or using the Go SDK:

result, err := client.RunDiscovery(ctx, &v1.RunDiscoveryParams{
    EnvironmentID: "env_abc123",
    MoleculeID:    v1.NewOptString("github"),
})

What Gets Discovered

Each molecule defines the entity types and relationship types it discovers. For example, the GitHub molecule discovers:

• Entity types: Repositories, users, organizations, pull requests, branches
• Relationship types: OWNS (org → repo), CONTRIBUTES_TO (user → repo), MEMBER_OF (user → org)

You can see exactly what a molecule discovers on its integration page.

Discovery Status

Each discovery run progresses through these states:

State	Description
Pending	Scheduled but not yet started
Running	Actively scanning the external service
Completed	Finished successfully
Failed	Encountered an error

You can check the status of a discovery run in the UI under your integration, or via the API:

status, err := client.GetDiscoveryRun(ctx, &v1.GetDiscoveryRunParams{
    EnvironmentID: "env_abc123",
    RunID:         "run_xyz",
})

log.Printf("Status: %s, Entities: %d\n", status.Status, status.EntitiesCreated)

Incremental vs Full Discovery

• Full discovery scans everything from scratch. This happens on the first run and can be triggered manually.
• Incremental discovery only processes changes since the last run. The molecule receives the IncrementalFrom timestamp and uses it to filter API calls to the external service.

Incremental discovery is significantly faster and uses fewer API calls, which matters for rate-limited services like GitHub.

Troubleshooting

Discovery Not Finding Entities

• Check credentials: Ensure the molecule's token/credentials have sufficient permissions to read the resources you expect
• Check scope: Some molecules filter by organization, project, or namespace — verify your configuration includes the right scope
• Check logs: View molecule logs in the UI for detailed error messages

Discovery Is Slow

• Large initial scan: The first discovery run scans everything and may take time for large organizations
• API rate limits: Molecules respect external API rate limits, which can slow discovery
• Incremental mode: After the initial scan, subsequent runs should be fast

Stale Data

• Check schedule: Verify the discovery interval is appropriate for your needs
• Manual trigger: Run discovery manually to force an immediate update
• Webhook setup: For near real-time updates, configure webhooks if the molecule supports them

Next Steps

• AI Tools — Learn how molecules provide tools for AI interaction
• Skills — Higher-level workflows across platforms
• Visualizations — Custom visualizations from molecules
• Building Molecules — Create your own discovery plugins