Skip to main content

Go SDK

The SixDegree Go SDK is a type-safe, auto-generated client for interacting with the SixDegree platform API. The SDK is automatically generated from the OpenAPI specification using ogen, ensuring it stays in sync with the platform API.

Installation​

go get github.com/sixdegree-ai/go-sixdegree

Requirements:

  • Go 1.24 or later

Quick Start​

package main

import (
    "context"
    "log"

    v1 "github.com/sixdegree-ai/go-sixdegree/sixdegree/v1"
)

func main() {
    // Create client with API token
    client, err := v1.NewClient(
        "https://api.sixdegree.ai",
        v1.WithToken("your-api-token"),
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // List environments
    envs, err := client.ListEnvironments(ctx, &v1.ListEnvironmentsParams{})
    if err != nil {
        log.Fatal(err)
    }

    for _, env := range envs.Environments {
        log.Printf("Environment: %s (ID: %s)\n", env.Name, env.ID)
    }
}

Authentication​

API Token Authentication​

The SDK supports token-based authentication using the WithToken option:

client, err := v1.NewClient(
    "https://api.sixdegree.ai",
    v1.WithToken("sd_your_api_token"),
)

Environment Variable​

Set the token via environment variable:

export SIXDEGREE_API_TOKEN="sd_your_api_token"
import "os"

token := os.Getenv("SIXDEGREE_API_TOKEN")
client, err := v1.NewClient(
    "https://api.sixdegree.ai",
    v1.WithToken(token),
)

Custom HTTP Client​

For advanced scenarios, provide a custom HTTP client:

import "net/http"

httpClient := &http.Client{
    Timeout: 30 * time.Second,
}

client, err := v1.NewClient(
    "https://api.sixdegree.ai",
    v1.WithClient(httpClient),
    v1.WithToken("your-token"),
)

Environments​

Environments provide isolated namespaces for your entities and relationships.

List Environments​

result, err := client.ListEnvironments(ctx, &v1.ListEnvironmentsParams{})
if err != nil {
    return err
}

for _, env := range result.Environments {
    log.Printf("Environment: %s (ID: %s)\n", env.Name, env.ID)
}

Get Environment​

env, err := client.GetEnvironment(ctx, &v1.GetEnvironmentParams{
    EnvironmentID: "env_abc123",
})
if err != nil {
    return err
}

log.Printf("Environment: %s\n", env.Name)
log.Printf("Created: %s\n", env.CreatedAt)

Create Environment​

result, err := client.CreateEnvironment(ctx, &v1.CreateEnvironmentRequest{
    Name:        "Production",
    Description: v1.NewOptString("Production environment"),
})
if err != nil {
    return err
}

log.Printf("Created environment: %s\n", result.ID)

Delete Environment​

err := client.DeleteEnvironment(ctx, &v1.DeleteEnvironmentParams{
    EnvironmentID: "env_abc123",
})
if err != nil {
    return err
}

Entities​

Entities represent the nodes in your knowledge graph.

List Entities​

result, err := client.ListEntities(ctx, &v1.ListEntitiesParams{
    EnvironmentID: "env_abc123",
    Kind:          v1.NewOptString("Repository"),
    Limit:         v1.NewOptInt(100),
    Offset:        v1.NewOptInt(0),
})
if err != nil {
    return err
}

for _, entity := range result.Entities {
    log.Printf("Entity: %s (Kind: %s)\n", entity.Name, entity.Kind)
}

log.Printf("Total: %d, Page: %d of %d\n",
    result.Total, result.Page, result.TotalPages)

Get Entity​

entity, err := client.GetEntity(ctx, &v1.GetEntityParams{
    EnvironmentID: "env_abc123",
    EntityUID:     "repo_xyz789",
})
if err != nil {
    return err
}

log.Printf("Entity: %s\n", entity.Name)
log.Printf("Kind: %s\n", entity.Kind)
log.Printf("Properties: %+v\n", entity.Properties)

Create Entity​

result, err := client.CreateEntity(ctx, &v1.CreateEntityRequest{
    EnvironmentID: "env_abc123",
    Group:         "core",
    Version:       "v1",
    Namespace:     "default",
    Kind:          "Service",
    Name:          "auth-service",
    Properties: v1.NewOptCreateEntityReqProperties(v1.CreateEntityReqProperties{
        "url": "https://auth.example.com",
        "port": 8080,
    }),
})
if err != nil {
    return err
}

log.Printf("Created entity: %s\n", result.UID)

Update Entity​

result, err := client.UpdateEntity(ctx, &v1.UpdateEntityRequest{
    EnvironmentID: "env_abc123",
    EntityUID:     "service_xyz",
    Properties: v1.NewOptUpdateEntityReqProperties(v1.UpdateEntityReqProperties{
        "status": "active",
        "replicas": 3,
    }),
})
if err != nil {
    return err
}

Delete Entity​

err := client.DeleteEntity(ctx, &v1.DeleteEntityParams{
    EnvironmentID: "env_abc123",
    EntityUID:     "service_xyz",
})
if err != nil {
    return err
}

Bulk Create Entities​

For creating multiple entities efficiently:

entities := []v1.CreateEntityRequest{
    {
        Group:     "core",
        Version:   "v1",
        Namespace: "default",
        Kind:      "Service",
        Name:      "api-service",
    },
    {
        Group:     "core",
        Version:   "v1",
        Namespace: "default",
        Kind:      "Service",
        Name:      "web-service",
    },
}

result, err := client.CreateEntitiesBulk(ctx, &v1.CreateEntitiesBulkRequest{
    EnvironmentID: "env_abc123",
    Entities:      entities,
})
if err != nil {
    return err
}

log.Printf("Created: %d, Failed: %d\n", result.SuccessCount, result.FailureCount)
for _, failure := range result.Failures {
    log.Printf("Failed: %s - %s\n", failure.Name, failure.Error)
}

Get Entity Relationships​

result, err := client.GetEntityRelations(ctx, &v1.GetEntityRelationsParams{
    EnvironmentID: "env_abc123",
    EntityUID:     "repo_xyz",
})
if err != nil {
    return err
}

for _, rel := range result.Relations {
    log.Printf("%s -[%s]-> %s\n", rel.From, rel.Type, rel.To)
}

Create Relationship​

result, err := client.CreateEntityRelation(ctx, &v1.CreateEntityRelationRequest{
    EnvironmentID: "env_abc123",
    From:          "repo_xyz",
    To:            "service_abc",
    Type:          "DEPLOYS_TO",
    Properties: v1.NewOptCreateEntityRelationReqProperties(v1.CreateEntityRelationReqProperties{
        "environment": "production",
        "version": "v1.2.3",
    }),
})
if err != nil {
    return err
}

log.Printf("Created relationship: %s\n", result.ID)

Bulk Create Relationships​

relations := []v1.CreateEntityRelationRequest{
    {From: "repo1", To: "service1", Type: "DEPLOYS_TO"},
    {From: "repo2", To: "service2", Type: "DEPLOYS_TO"},
}

result, err := client.CreateEntityRelationsBulk(ctx, &v1.CreateEntityRelationsBulkRequest{
    EnvironmentID: "env_abc123",
    Relations:     relations,
})
if err != nil {
    return err
}

log.Printf("Created: %d, Failed: %d\n", result.SuccessCount, result.FailureCount)

Chat​

The Chat API provides AI-powered interactions with your knowledge graph.

Create Chat Session​

result, err := client.CreateChat(ctx, &v1.CreateChatRequest{
    EnvironmentID: "env_abc123",
    ModelID:       v1.NewOptString("claude-3-5-sonnet-20241022"),
})
if err != nil {
    return err
}

chatID := result.ID
log.Printf("Created chat session: %s\n", chatID)

List Chat Sessions​

result, err := client.ListChats(ctx, &v1.ListChatsParams{
    EnvironmentID: "env_abc123",
    Limit:         v1.NewOptInt(20),
})
if err != nil {
    return err
}

for _, chat := range result.Chats {
    log.Printf("Chat: %s - %s\n", chat.ID, chat.Title)
}

Get Chat History​

result, err := client.GetChat(ctx, &v1.GetChatParams{
    EnvironmentID: "env_abc123",
    ChatID:        "chat_xyz",
})
if err != nil {
    return err
}

for _, msg := range result.Messages {
    log.Printf("[%s] %s\n", msg.Role, msg.Content)
}

Send Chat Message (Non-Streaming)​

result, err := client.CreateChatCompletions(ctx, &v1.CreateChatCompletionsRequest{
    EnvironmentID: "env_abc123",
    ChatID:        "chat_xyz",
    Messages: []v1.ChatMessage{
        {
            Role:    "user",
            Content: "What repositories depend on the auth service?",
        },
    },
    Stream: v1.NewOptBool(false),
})
if err != nil {
    return err
}

log.Printf("Response: %s\n", result.Choices[0].Message.Content)

Streaming Chat​

For real-time streaming responses:

import "io"

result, err := client.CreateChatCompletions(ctx, &v1.CreateChatCompletionsRequest{
    EnvironmentID: "env_abc123",
    ChatID:        "chat_xyz",
    Messages: []v1.ChatMessage{
        {
            Role:    "user",
            Content: "Explain the architecture of my system",
        },
    },
    Stream: v1.NewOptBool(true),
})
if err != nil {
    return err
}

// Handle streaming response
for {
    chunk, err := result.Read()
    if err == io.EOF {
        break
    }
    if err != nil {
        return err
    }

    if len(chunk.Choices) > 0 {
        fmt.Print(chunk.Choices[0].Delta.Content)
    }
}

Chat Suggestions​

Get AI-suggested questions based on the knowledge graph:

result, err := client.GetChatSuggestions(ctx, &v1.GetChatSuggestionsParams{
    EnvironmentID: "env_abc123",
})
if err != nil {
    return err
}

for _, suggestion := range result.Suggestions {
    log.Printf("Suggested question: %s\n", suggestion.Text)
}

MCP (Model Context Protocol)​

List MCP Endpoints​

result, err := client.ListMcpendpoints(ctx, &v1.ListMcpendpointsParams{
    EnvironmentID: "env_abc123",
})
if err != nil {
    return err
}

for _, endpoint := range result.Endpoints {
    log.Printf("MCP Endpoint: %s (%s)\n", endpoint.Name, endpoint.Transport)
}

Create MCP Endpoint​

result, err := client.CreateMcpendpoint(ctx, &v1.CreateMcpendpointRequest{
    EnvironmentID: "env_abc123",
    Name:          "PostgreSQL Tools",
    URL:           "https://mcp-postgres.example.com",
    Transport:     "http",
    AuthConfig: v1.NewOptCreateMcpendpointReqAuthConfig(v1.CreateMcpendpointReqAuthConfig{
        "type":  "bearer",
        "token": "your-token",
    }),
})
if err != nil {
    return err
}

log.Printf("Created MCP endpoint: %s\n", result.ID)

List Available MCP Tools​

result, err := client.ListMcptools(ctx, &v1.ListMcptoolsParams{
    EnvironmentID: "env_abc123",
    McpendpointID: v1.NewOptString("mcp_xyz"),
})
if err != nil {
    return err
}

for _, tool := range result.Tools {
    log.Printf("Tool: %s - %s\n", tool.Name, tool.Description)
}

Discovery​

List Configured Molecules​

result, err := client.ListConfiguredMolecules(ctx, &v1.ListConfiguredMoleculesParams{
    EnvironmentID: "env_abc123",
})
if err != nil {
    return err
}

for _, mol := range result.Molecules {
    log.Printf("Molecule: %s (Status: %s)\n", mol.Name, mol.Status)
}

Create Configured Molecule​

result, err := client.CreateConfiguredMolecule(ctx, &v1.CreateConfiguredMoleculeRequest{
    EnvironmentID: "env_abc123",
    MoleculeID:    "github",
    Configuration: v1.NewOptCreateConfiguredMoleculeReqConfiguration(
        v1.CreateConfiguredMoleculeReqConfiguration{
            "token": "ghp_your_token",
            "orgs":  []string{"myorg"},
        },
    ),
})
if err != nil {
    return err
}

log.Printf("Configured molecule: %s\n", result.ID)

Run Discovery​

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

log.Printf("Discovery run started: %s\n", result.RunID)

Check Discovery Status​

result, err := client.GetDiscoveryRun(ctx, &v1.GetDiscoveryRunParams{
    EnvironmentID: "env_abc123",
    RunID:         "run_xyz",
})
if err != nil {
    return err
}

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

Context and Timeouts​

Use context for cancellation and timeouts:

import "time"

// Request with timeout
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

result, err := client.ListEntities(ctx, &v1.ListEntitiesParams{
    EnvironmentID: "env_abc123",
})
if err != nil {
    if errors.Is(err, context.DeadlineExceeded) {
        log.Println("Request timed out")
    }
    return err
}

Error Handling​

The SDK uses structured errors from ogen:

import "github.com/ogen-go/ogen/ogenerrors"

result, err := client.GetEntity(ctx, &v1.GetEntityParams{
    EnvironmentID: "env_abc123",
    EntityUID:     "entity_xyz",
})
if err != nil {
    // Check for specific error types
    if errors.Is(err, context.Canceled) {
        log.Println("Request was canceled")
        return err
    }

    if errors.Is(err, context.DeadlineExceeded) {
        log.Println("Request timed out")
        return err
    }

    // Check for API errors
    var apiErr *ogenerrors.ErrorStatusCode
    if errors.As(err, &apiErr) {
        log.Printf("API error (status %d): %s\n", apiErr.StatusCode, apiErr.Response)
        return err
    }

    log.Printf("Unexpected error: %v\n", err)
    return err
}

Handling Not Found Errors​

entity, err := client.GetEntity(ctx, &v1.GetEntityParams{
    EnvironmentID: "env_abc123",
    EntityUID:     "entity_xyz",
})
if err != nil {
    var apiErr *ogenerrors.ErrorStatusCode
    if errors.As(err, &apiErr) && apiErr.StatusCode == 404 {
        log.Println("Entity not found")
        return nil // Handle gracefully
    }
    return err
}

Pagination​

Handle paginated responses:

const pageSize = 100
offset := 0

for {
    result, err := client.ListEntities(ctx, &v1.ListEntitiesParams{
        EnvironmentID: "env_abc123",
        Limit:         v1.NewOptInt(pageSize),
        Offset:        v1.NewOptInt(offset),
    })
    if err != nil {
        return err
    }

    // Process entities
    for _, entity := range result.Entities {
        log.Printf("Entity: %s\n", entity.Name)
    }

    // Check if more pages
    if offset+pageSize >= result.Total {
        break
    }

    offset += pageSize
}

Testing​

Using the SDK in Tests​

package myapp_test

import (
    "context"
    "testing"

    v1 "github.com/sixdegree-ai/go-sixdegree/sixdegree/v1"
)

func TestCreateEntity(t *testing.T) {
    client, err := v1.NewClient(
        "https://api.sixdegree.ai",
        v1.WithToken(getTestToken()),
    )
    if err != nil {
        t.Fatal(err)
    }

    ctx := context.Background()

    result, err := client.CreateEntity(ctx, &v1.CreateEntityRequest{
        EnvironmentID: "test_env",
        Group:         "core",
        Version:       "v1",
        Namespace:     "default",
        Kind:          "TestEntity",
        Name:          "test-entity",
    })
    if err != nil {
        t.Fatalf("Failed to create entity: %v", err)
    }

    if result.UID == "" {
        t.Error("Expected non-empty entity UID")
    }

    // Cleanup
    defer client.DeleteEntity(ctx, &v1.DeleteEntityParams{
        EnvironmentID: "test_env",
        EntityUID:     result.UID,
    })
}

func getTestToken() string {
    // Load from environment or test config
    return os.Getenv("SIXDEGREE_TEST_TOKEN")
}

Complete Example​

Here's a complete example that demonstrates common workflows:

package main

import (
    "context"
    "log"
    "time"

    v1 "github.com/sixdegree-ai/go-sixdegree/sixdegree/v1"
)

func main() {
    // Create client
    client, err := v1.NewClient(
        "https://api.sixdegree.ai",
        v1.WithToken("your-api-token"),
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
    defer cancel()

    envID := "env_abc123"

    // 1. Create entities
    log.Println("Creating entities...")
    entities := []v1.CreateEntityRequest{
        {
            Group:     "core",
            Version:   "v1",
            Namespace: "default",
            Kind:      "Repository",
            Name:      "api-service",
            Properties: v1.NewOptCreateEntityReqProperties(v1.CreateEntityReqProperties{
                "language": "Go",
                "url":      "https://github.com/org/api-service",
            }),
        },
        {
            Group:     "core",
            Version:   "v1",
            Namespace: "default",
            Kind:      "Service",
            Name:      "api-production",
            Properties: v1.NewOptCreateEntityReqProperties(v1.CreateEntityReqProperties{
                "url": "https://api.prod.example.com",
            }),
        },
    }

    bulkResult, err := client.CreateEntitiesBulk(ctx, &v1.CreateEntitiesBulkRequest{
        EnvironmentID: envID,
        Entities:      entities,
    })
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Created %d entities\n", bulkResult.SuccessCount)

    // 2. Create relationship
    log.Println("Creating relationship...")
    _, err = client.CreateEntityRelation(ctx, &v1.CreateEntityRelationRequest{
        EnvironmentID: envID,
        From:          bulkResult.Entities[0].UID,
        To:            bulkResult.Entities[1].UID,
        Type:          "DEPLOYS_TO",
    })
    if err != nil {
        log.Fatal(err)
    }

    // 3. Query entities
    log.Println("Querying entities...")
    listResult, err := client.ListEntities(ctx, &v1.ListEntitiesParams{
        EnvironmentID: envID,
        Kind:          v1.NewOptString("Repository"),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, entity := range listResult.Entities {
        log.Printf("Found: %s (UID: %s)\n", entity.Name, entity.UID)

        // Get relationships
        relations, err := client.GetEntityRelations(ctx, &v1.GetEntityRelationsParams{
            EnvironmentID: envID,
            EntityUID:     entity.UID,
        })
        if err != nil {
            log.Printf("Failed to get relations: %v\n", err)
            continue
        }

        for _, rel := range relations.Relations {
            log.Printf("  -> %s [%s]\n", rel.To, rel.Type)
        }
    }

    // 4. Chat with AI about the entities
    log.Println("Creating chat session...")
    chatResult, err := client.CreateChat(ctx, &v1.CreateChatRequest{
        EnvironmentID: envID,
    })
    if err != nil {
        log.Fatal(err)
    }

    completion, err := client.CreateChatCompletions(ctx, &v1.CreateChatCompletionsRequest{
        EnvironmentID: envID,
        ChatID:        chatResult.ID,
        Messages: []v1.ChatMessage{
            {
                Role:    "user",
                Content: "What services are deployed from the api-service repository?",
            },
        },
        Stream: v1.NewOptBool(false),
    })
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("AI Response: %s\n", completion.Choices[0].Message.Content)
}

Additional Resources​