> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchport.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Go SDK Quickstart

> Get started with the Switchport Go SDK in 5 minutes

## Prerequisites

* Go 1.21 or higher
* A Switchport account ([sign up at switchport.ai](https://switchport.ai))
* Your Switchport API key

## Installation

Install the Switchport SDK using `go get`:

```bash theme={null}
go get github.com/switchport-ai/switchport-go
```

Or add it to your `go.mod`:

```go theme={null}
require github.com/switchport-ai/switchport-go v0.1.0
```

Then run:

```bash theme={null}
go mod tidy
```

## Get Your API Key

<Steps>
  <Step title="Sign in to Switchport">
    Go to [switchport.ai](https://switchport.ai) and log in to your account.
  </Step>

  <Step title="Navigate to Settings">
    Go to **Settings** → **API Keys** in the dashboard.
  </Step>

  <Step title="Copy your API key">
    Copy your API key (it starts with `sp_`).
  </Step>
</Steps>

## Set Your API Key

Set your API key as an environment variable:

<CodeGroup>
  ```bash Linux/Mac theme={null}
  export SWITCHPORT_API_KEY=sp_your_key_here
  ```

  ```powershell Windows (PowerShell) theme={null}
  $env:SWITCHPORT_API_KEY="sp_your_key_here"
  ```

  ```bash .env file theme={null}
  echo "SWITCHPORT_API_KEY=sp_your_key_here" >> .env
  ```
</CodeGroup>

## Create Your First Prompt

Before using the SDK, you need to create a prompt in the Switchport dashboard:

<Steps>
  <Step title="Create a prompt config">
    1. Go to **Prompts** → **New Prompt Config**
    2. Name: "Welcome Message"
    3. Key: `welcome-message`
    4. Click **Create**
  </Step>

  <Step title="Add a version">
    1. Click **Add Version**
    2. Model: Select `gpt-5` (or another model)
    3. Prompt: `Write a friendly welcome message for {{name}}.`
    4. Click **Save**
  </Step>

  <Step title="Publish the version">
    Click **Publish** on the version you just created.
  </Step>
</Steps>

## Configure LLM API Keys

The SDK calls LLMs on your behalf, so you need to configure your LLM API keys:

<Steps>
  <Step title="Go to Organization Settings">
    Navigate to **Settings** → **Organization Settings**
  </Step>

  <Step title="Add your LLM API keys">
    Add API keys for the LLM providers you want to use:

    * OpenAI API key (for GPT models)
    * Anthropic API key (for Claude models)
    * Google API key (for Gemini models)
  </Step>

  <Step title="Save">
    Click **Save** to store your API keys securely.
  </Step>
</Steps>

## Execute Your First Prompt

Create a file `main.go`:

```go theme={null}
package main

import (
	"fmt"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	// Initialize client (reads API key from environment)
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Execute a prompt
	response, err := client.Prompts.Execute(
		"welcome-message",
		nil, // no subject
		map[string]interface{}{"name": "Alice"},
	)
	if err != nil {
		log.Fatalf("Failed to execute prompt: %v", err)
	}

	fmt.Println("Generated text:")
	fmt.Println(response.Text)
	fmt.Printf("\nModel: %s\n", response.Model)
	fmt.Printf("Version: %s\n", response.VersionName)
}
```

Run it:

```bash theme={null}
go run main.go
```

You should see output like:

```
Generated text:
Hello Alice! Welcome to our platform. We're excited to have you here!

Model: gpt-5
Version: v1
```

## Record Your First Metric

Now let's track a metric. First, create a metric definition in the dashboard:

<Steps>
  <Step title="Create metric definition">
    1. Go to **Metrics** → **New Metric**
    2. Key: `satisfaction`
    3. Name: "User Satisfaction"
    4. Type: `float`
    5. Click **Create**
  </Step>
</Steps>

Then record a metric in your code:

```go theme={null}
package main

import (
	"fmt"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Execute prompt with subject identification
	subject := map[string]interface{}{"user_id": "user_123"}
	response, err := client.Prompts.Execute(
		"welcome-message", subject,
		map[string]interface{}{"name": "Alice"},
	)
	if err != nil {
		log.Fatalf("Failed to execute prompt: %v", err)
	}

	fmt.Println(response.Text)

	// Simulate user feedback (1-5 stars)
	userRating := 4.5

	// Record metric with same subject
	result, err := client.Metrics.Record(
		"satisfaction",
		userRating,
		subject, // Same subject!
		nil,     // timestamp (nil = current time)
	)
	if err != nil {
		log.Fatalf("Failed to record metric: %v", err)
	}

	fmt.Printf("\nMetric recorded! Event ID: %s\n", result.MetricEventID)
}
```

<Warning>
  Always use the same subject when executing prompts and recording metrics. This ensures metrics are correctly aggregated per prompt version.
</Warning>

## Next Steps

<Columns cols={2}>
  <Card title="A/B Testing" icon="flask" href="/sdk/go/ab-testing">
    Learn how to run A/B tests with multiple prompt versions
  </Card>

  <Card title="API Reference" icon="code" href="/sdk/go/reference/client">
    Explore the full API reference
  </Card>

  <Card title="Examples" icon="book" href="/sdk/go/examples/basic-usage">
    See more code examples
  </Card>

  <Card title="Core Concepts" icon="lightbulb" href="/concepts/core-concepts">
    Understand key concepts
  </Card>
</Columns>