### Link, Get, and Install Extensions

Source: https://github.com/kong/kongctl/blob/main/skills/kongctl-extension-builder/SKILL.md

Commands for linking, getting information about, and installing extensions locally.

```sh
kongctl link extension <extension-dir>
kongctl get extension <publisher>/<name>
kongctl get <resource>
```

```sh
kongctl install extension <extension-dir>
kongctl list extensions
kongctl uninstall extension <publisher>/<name>
```

--------------------------------

### Staged Synchronization Examples

Source: https://github.com/kong/kongctl/blob/main/internal/cmd/root/verbs/help/templates/sync.md

Provides an example of a staged synchronization workflow, starting with less risky resource types like portals and then proceeding to APIs with a dry run for review.

```bash
# Stage 1: Sync portals (less risky)
kongctl sync -f portals.yaml

# Stage 2: Sync APIs (review deletions)
kongctl sync -f apis.yaml --dry-run
# ... review ...
kongctl sync -f apis.yaml
```

--------------------------------

### CI/CD Workflow Example

Source: https://github.com/kong/kongctl/blob/main/internal/cmd/root/verbs/help/templates/plan.md

Example of using `kongctl plan` within a CI/CD pipeline for automated plan generation and application.

```bash
# In CI pipeline
kongctl plan -f ./configs/ --output-file plan.json

# Review plan (automated checks)
./scripts/validate-plan.sh plan.json

# In CD pipeline
kongctl apply --plan plan.json --auto-approve
```

--------------------------------

### List and View Example Configurations

Source: https://github.com/kong/kongctl/blob/main/docs/troubleshooting.md

Lists all files within the 'docs/examples/declarative/basic/' directory and then displays the content of a specific example file named 'api.yaml'. Useful for understanding how to structure configurations.

```bash
# Review example configurations
ls docs/examples/declarative/
cat docs/examples/declarative/basic/api.yaml
```

--------------------------------

### Check CLI Installation

Source: https://github.com/kong/kongctl/blob/main/skills/kongctl-declarative/SKILL.md

Confirm that the kongctl CLI is installed and runnable.

```bash
kongctl version
```

--------------------------------

### Portal Resource Example

Source: https://github.com/kong/kongctl/blob/main/skills/kongctl-declarative/references/resources.md

A basic example of a `portals` resource configuration, including common fields.

```yaml
portals:
  - ref: dev-portal
    name: "my-dev-portal"
    display_name: "My Dev Portal"
    default_api_visibility: "private"
    default_page_visibility: "private"
```

--------------------------------

### Example Starter Manifest

Source: https://github.com/kong/kongctl/blob/main/skills/kongctl-declarative/SKILL.md

A static YAML pattern demonstrating the structure for `_defaults`, `control_planes`, `portals`, and `apis`. This serves as a compact fallback and example of expected results.

```yaml
_defaults:
  kongctl:
    namespace: platform-dev
    protected: false

control_planes:
  - ref: cp-main
    name: "my-control-plane"
    cluster_type: "CLUSTER_TYPE_CONTROL_PLANE"

portals:
  - ref: dev-portal
    name: "my-dev-portal"
    display_name: "My Dev Portal"
    default_api_visibility: "private"
    default_page_visibility: "private"

apis:
  - ref: payments-api
    name: !file <existing-openapi-path>#info.title
    description: !file <existing-openapi-path>#info.description
    versions:
      - ref: payments-v1
        version: !file <existing-openapi-path>#info.version
        spec: !file <existing-openapi-path>
    publications:
      - ref: payments-publication
        portal_id: !ref dev-portal#id
        visibility: public
```

--------------------------------

### Team-Alpha Configuration Example

Source: https://github.com/kong/kongctl/blob/main/docs/declarative.md

Example of a configuration file for the 'team-alpha' namespace, demonstrating how to set default namespaces and reference APIs.

```yaml
# team-alpha/config.yaml
_defaults:
  kongctl:
    namespace: team-alpha

apis:
  - ref: frontend-api
    name: "Frontend API"
    # Automatically in team-alpha namespace
```

--------------------------------

### Check decK Installation

Source: https://github.com/kong/kongctl/blob/main/skills/kongctl-declarative/SKILL.md

Confirm that decK is installed for Kong Gateway configuration.

```bash
deck version
```

--------------------------------

### Namespace Support Example

Source: https://github.com/kong/kongctl/blob/main/internal/cmd/root/verbs/help/templates/plan.md

When using namespaces, the plan output indicates the namespace context for each change.

```bash
# Plan shows namespace grouping
kongctl plan -f team-configs/

Planning changes for namespace: team-alpha
- CREATE api "frontend-api"

Planning changes for namespace: team-beta  
- CREATE api "backend-api"
```

--------------------------------

### Common GitHub Actions Job Steps

Source: https://github.com/kong/kongctl/blob/main/skills/kongctl-declarative/references/cicd-github-actions.md

Includes essential steps for most kongctl workflows: checking out the repository, installing kongctl, and installing deck. These are foundational for running declarative commands.

```yaml
steps:
  - uses: actions/checkout@v4
  - name: Install kongctl
    uses: kong/setup-kongctl@v1
  - name: Install deck
    uses: kong/setup-deck@v1
```

--------------------------------

### Manual Install for Claude

Source: https://github.com/kong/kongctl/blob/main/skills/README.md

Manually installs kongctl skills for Claude by creating symbolic links. Target path is `.claude/skills/`.

```sh
ln -s ../../skills/kongctl-declarative .claude/skills/kongctl-declarative
```

```sh
ln -s ../../skills/kongctl-extension-builder .claude/skills/kongctl-extension-builder
```

--------------------------------

### Install kongctl on Linux

Source: https://github.com/kong/kongctl/blob/main/README.md

Download and install the latest kongctl release for Linux. This involves downloading a zip archive, unzipping it, and placing the executable in a system path.

```shell
curl -sL https://github.com/Kong/kongctl/releases/latest/download/kongctl_linux_amd64.zip -o kongctl_linux_amd64.zip
unzip kongctl_linux_amd64.zip -d kongctl-linux-amd64
sudo install kongctl-linux-amd64/kongctl /usr/local/bin/kongctl
```

--------------------------------

### Manual Install for Codex, Cursor, Opencode

Source: https://github.com/kong/kongctl/blob/main/skills/README.md

Manually installs kongctl skills for Codex, Cursor, and Opencode by creating symbolic links. Target path is typically `.agents/skills/`.

```sh
ln -s ../../skills/kongctl-declarative .agents/skills/kongctl-declarative
```

```sh
ln -s ../../skills/kongctl-extension-builder .agents/skills/kongctl-extension-builder
```

--------------------------------

### Using kongctl Explain and Scaffold

Source: https://github.com/kong/kongctl/blob/main/skills/kongctl-declarative/references/resources.md

Demonstrates how to use `kongctl explain` to inspect resource schemas and `kongctl scaffold` to generate resource configurations.

```bash
kongctl explain api --extended -o text
kongctl explain api.publications.portal_id
kongctl scaffold api
kongctl scaffold api.versions
```

--------------------------------

### Manage Local Extensions

Source: https://github.com/kong/kongctl/blob/main/docs/extensions.md

Commands for linking, getting, listing, and installing extensions locally.

```sh
kongctl link extension ./my-extension
kongctl get extension kong/foo
kongctl list extensions
kongctl get foo --help
kongctl get foo
```

--------------------------------

### Full Environment Sync Examples

Source: https://github.com/kong/kongctl/blob/main/internal/cmd/root/verbs/help/templates/sync.md

Shows workflows for synchronizing entire environments, including development with auto-approval and production with a pre-generated plan for review.

```bash
# Development environment - full sync
kongctl sync -f environments/dev/ --recursive --auto-approve
```

```bash
# Production - careful sync with review
kongctl plan -f environments/prod/ --recursive -o prod-plan.json
# ... review plan carefully ...
kongctl sync --plan prod-plan.json
```

--------------------------------

### Create Directory and Configuration File

Source: https://github.com/kong/kongctl/blob/main/docs/declarative.md

Sets up a working directory and creates an initial `portal.yaml` file for declarative configuration.

```shell
mkdir kong-portal && cd kong-portal
```

```yaml
portals:
  - ref: my-portal
    name: "my-developer-portal"
    display_name: "My Developer Portal"
    description: "API documentation for developers"
    authentication_enabled: false
    default_api_visibility: "public"
    default_page_visibility: "public"

apis:
  - ref: users-api
    name: "Users API"
    description: "API for user management"

    publications:
      - ref: users-api-publication
        portal_id: my-portal
```

--------------------------------

### Get Analytics Reports (SDK Example)

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/external/team-a/docs/overview.md

An SDK method to fetch pre-built analytics reports.

```APIDOC
## getAnalyticsReports (SDK Method)

### Description
Fetches pre-built analytics reports for various business metrics like engagement and acquisition.

### Parameters
- **report_type** (string) - Required - The type of report to retrieve (e.g., 'engagement', 'acquisition').
- **start_date** (string) - Required - The start date for the report period (YYYY-MM-DD).
- **end_date** (string) - Required - The end date for the report period (YYYY-MM-DD).

### Request Example
```javascript
const engagementReport = await analytics.getAnalyticsReports({
  report_type: 'engagement',
  start_date: '2024-01-01',
  end_date: '2024-01-31'
});
```
```

--------------------------------

### Get Specific API Details

Source: https://github.com/kong/kongctl/blob/main/README.md

Example of retrieving detailed information for a specific API by its name.

```shell
kongctl get api users-api
```

--------------------------------

### Basic Synchronization Examples

Source: https://github.com/kong/kongctl/blob/main/internal/cmd/root/verbs/help/templates/sync.md

Demonstrates basic usage of the `kongctl sync` command with a single configuration file, auto-approval, and dry run options.

```bash
kongctl sync -f api-config.yaml
```

```bash
kongctl sync -f config.yaml --auto-approve
```

```bash
kongctl sync -f config.yaml --dry-run
```

--------------------------------

### Basic Planning Examples

Source: https://github.com/kong/kongctl/blob/main/internal/cmd/root/verbs/help/templates/plan.md

Generate an execution plan for your Kong Konnect resources using various input methods.

```bash
# Generate plan for a single file
kongctl plan -f api-config.yaml
```

```bash
# Generate plan for multiple files
kongctl plan -f portals.yaml -f apis.yaml -f auth.yaml
```

```bash
# Generate plan from directory
kongctl plan -f ./configs/
```

```bash
# Generate plan recursively from directory tree
kongctl plan -f ./configs/ --recursive
```

--------------------------------

### Get Segment Customers (SDK Example)

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/external/team-a/docs/overview.md

An SDK method to retrieve customers belonging to a specific segment.

```APIDOC
## getSegmentCustomers (SDK Method)

### Description
Retrieves a list of customers who belong to a specified segment. This is useful for targeting specific customer groups.

### Parameters
- **segment_id** (string) - Required - The unique identifier of the segment.

### Request Example
```javascript
const highValueCustomers = await analytics.getSegmentCustomers('high_value_segment');
```
```

--------------------------------

### Get Analytics Report

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/external/team-a/README.md

Example using curl to retrieve an analytics report. Requires an Authorization header and query parameters to specify the report type and date range.

```bash
# Get analytics report
curl -X GET "https://api.company.com/customer-analytics/v1/analytics/reports?report_type=retention&start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Example Configuration File

Source: https://github.com/kong/kongctl/blob/main/README.md

Demonstrates the structure of a kongctl configuration file with multiple profiles and nested settings for output and Konnect region.

```yaml
default:
  output: text
  konnect:
    region: us
second-profile:
  output: json
  konnect:
    region: eu
```

--------------------------------

### OpenID Connect Authentication Strategy Configuration

Source: https://github.com/kong/kongctl/blob/main/test/e2e/COVERAGE_ANALYSIS_2025-11-01.md

Configuration for an OpenID Connect authentication strategy, including issuer, scopes, and labels. This example demonstrates basic OIDC setup.

```yaml
  - ref: oidc-strategy
    name: "OpenID Connect"
    display_name: "OIDC Authentication"
    strategy_type: "openid_connect"
    configs:
      openid_connect:
        issuer: "https://auth.example.com"
        scopes: ["openid", "profile", "email"]
        # Additional OIDC configuration
    dcr_providers: []
    labels:
      auth-type: "oidc"
```

--------------------------------

### Fetch User Profile with JavaScript

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/external/platform/pages/getting-started.md

Example of retrieving the current user's profile using a GET request to the /v2/users/me endpoint. This requires a user token in the Authorization header.

```javascript
// Example: Get user profile
const profile = await fetch('/v2/users/me', {
  headers: {
    'Authorization': 'Bearer USER_TOKEN'
  }
});
```

--------------------------------

### Basic Apply Multiple Configuration Files

Source: https://github.com/kong/kongctl/blob/main/internal/cmd/root/verbs/help/templates/apply.md

Applies multiple configuration files sequentially.

```bash
# Apply multiple files
kongctl apply -f portals.yaml -f apis.yaml
```

--------------------------------

### Query Customer Data

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/external/team-a/docs/quickstart.md

Retrieve customer information and events using GET requests. Examples include fetching all customers, a specific customer, or their events. Replace YOUR_API_KEY with your actual key.

```bash
# Get all customers
curl -X GET "https://api.company.com/customer-analytics/v1/customers" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get specific customer details
curl -X GET "https://api.company.com/customer-analytics/v1/customers/customer_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get customer events
curl -X GET "https://api.company.com/customer-analytics/v1/customers/customer_123/events" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Minimal Manifest Example

Source: https://github.com/kong/kongctl/blob/main/skills/kongctl-extension-builder/SKILL.md

A basic kongctl-extension.yaml file defining the publisher, name, runtime command, and command paths for an extension.

```yaml
schema_version: 1

publisher: kong
name: foo

runtime:
  command: kongctl-ext-foo

command_paths:
  - path:
      - name: get
      - name: foo
        aliases: [foos]
```

--------------------------------

### Track Events and Get Customer Details (JavaScript/Node.js)

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/external/team-a/docs/examples.md

Use this snippet to track customer events and retrieve customer information. Ensure you have the '@company/customer-analytics' package installed and replace 'YOUR_API_KEY' with your actual API key.

```javascript
const CustomerAnalytics = require('@company/customer-analytics');
const analytics = new CustomerAnalytics('YOUR_API_KEY');

// Track events
await analytics.trackEvent({
  customer_id: 'customer_123',
  event_type: 'purchase',
  properties: { amount: 99.99 }
});

// Get customer details
const customer = await analytics.getCustomer('customer_123');
```

--------------------------------

### Pipeline Examples

Source: https://github.com/kong/kongctl/blob/main/internal/cmd/root/verbs/help/templates/plan.md

Integrate `kongctl plan` into pipelines by reading from stdin or piping output to other tools like `jq`.

```bash
# Generate plan from stdin
cat config.yaml | kongctl plan -f -
```

```bash
# Generate plan and pipe to jq for processing
kongctl plan -f config.yaml | jq '.changes[]'
```

```bash
# Generate plan and review specific changes
kongctl plan -f config.yaml | jq '.changes[] | select(.operation == "CREATE")'
```

--------------------------------

### Verify kongctl installation

Source: https://github.com/kong/kongctl/blob/main/README.md

Check the installed version of kongctl to ensure the installation was successful. Use the --full flag for detailed version information.

```shell
kongctl version --full
```

--------------------------------

### View Extended Kongctl Help

Source: https://github.com/kong/kongctl/blob/main/docs/troubleshooting.md

Displays detailed help information for specific kongctl commands like 'plan', 'apply', and 'sync'. Use this to understand command options and usage.

```bash
# View extended help
kongctl help plan
kongctl help apply
kongctl help sync
```

--------------------------------

### Install kongctl on macOS using Homebrew

Source: https://github.com/kong/kongctl/blob/main/README.md

Install the kongctl CLI tool on macOS using the Homebrew package manager. If you have a previous version installed, uninstall it first.

```shell
brew install --cask kong/kongctl/kongctl
```

--------------------------------

### GitOps Workflow Example

Source: https://github.com/kong/kongctl/blob/main/internal/cmd/root/verbs/help/templates/apply.md

A bash script demonstrating a GitOps workflow, including generating a plan, validating it, and applying it to production only on the main branch.

```bash
# In CI/CD pipeline
#!/bin/bash
set -e

# Generate plan
kongctl plan -f ./configs/ -o plan.json

# Validate plan meets policies
./scripts/validate-plan.sh plan.json

# Apply if validation passes
if [ "$BRANCH" = "main" ]; then
  kongctl apply --plan plan.json --auto-approve
fi
```

--------------------------------

### Upgrade All Installed Kongctl Extensions

Source: https://github.com/kong/kongctl/blob/main/docs/extensions.md

Commands to upgrade all installed Kongctl extensions. This process skips linked, local path, and GitHub source-clone installs without explicit tags.

```sh
kongctl upgrade extension
kongctl upgrade extensions
```

--------------------------------

### Build Main Binary

Source: https://github.com/kong/kongctl/blob/main/AGENTS.md

Build the main kongctl binary. CGO_ENABLED=0 is handled by the Makefile.

```shell
make build
```

--------------------------------

### Install and Uninstall Local Extensions

Source: https://github.com/kong/kongctl/blob/main/docs/extensions.md

Commands for installing and uninstalling extensions from a local path.

```sh
kongctl install extension ./my-extension
kongctl list extensions
kongctl uninstall extension kong/foo
```

--------------------------------

### Progressive Rollout Workflow

Source: https://github.com/kong/kongctl/blob/main/internal/cmd/root/verbs/help/templates/apply.md

Demonstrates a progressive rollout strategy by applying configuration in stages, starting with portals, then APIs, and finally publications.

```bash
# Stage 1: Apply portals only
kongctl apply -f portals.yaml

# Stage 2: Apply APIs
kongctl apply -f apis.yaml

# Stage 3: Apply publications
kongctl apply -f publications.yaml
```

--------------------------------

### Go Platform Client Initialization and Usage

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/external/platform/docs/examples.md

Initialize a Go client for the Platform API and demonstrate basic usage, including fetching the current user and logging in. Ensure the client is configured with an API key and a timeout.

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "time"
)

type PlatformClient struct {
    apiKey  string
    baseURL string
    client  *http.Client
}

type User struct {
    ID        string    `json:"id"`
    Username  string    `json:"username"`
    Name      string    `json:"name"`
    CreatedAt time.Time `json:"created_at"`
}

type LoginRequest struct {
    Username string `json:"username"`
    Password string `json:"password"`
}

type LoginResponse struct {
    AccessToken  string `json:"access_token"`
    RefreshToken string `json:"refresh_token"`
    TokenType    string `json:"token_type"`
    ExpiresIn    int    `json:"expires_in"`
}

func NewPlatformClient(apiKey string) *PlatformClient {
    return &PlatformClient{
        apiKey:  apiKey,
        baseURL: "https://api.company.com/v2",
        client:  &http.Client{Timeout: 30 * time.Second},
    }
}

func (c *PlatformClient) makeRequest(method, endpoint string, body interface{}) (*http.Response, error) {
    url := c.baseURL + endpoint
    
    var reqBody io.Reader
    if body != nil {
        jsonData, err := json.Marshal(body)
        if err != nil {
            return nil, err
        }
        reqBody = bytes.NewBuffer(jsonData)
    }

    req, err := http.NewRequest(method, url, reqBody)
    if err != nil {
        return nil, err
    }

    req.Header.Set("Authorization", "Bearer "+c.apiKey)
    req.Header.Set("Content-Type", "application/json")

    return c.client.Do(req)
}

func (c *PlatformClient) GetCurrentUser() (*User, error) {
    resp, err := c.makeRequest("GET", "/users/me", nil)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("API error: %d", resp.StatusCode)
    }

    var user User
    if err := json.NewDecoder(resp.Body).Decode(&user); err != nil {
        return nil, err
    }

    return &user, nil
}

func (c *PlatformClient) Login(username, password string) (*LoginResponse, error) {
    loginReq := LoginRequest{
        Username: username,
        Password: password,
    }

    resp, err := c.makeRequest("POST", "/auth/login", loginReq)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("login failed: %d", resp.StatusCode)
    }

    var loginResp LoginResponse
    if err := json.NewDecoder(resp.Body).Decode(&loginResp); err != nil {
        return nil, err
    }

    return &loginResp, nil
}

// Usage
func main() {
    client := NewPlatformClient("your_api_key_here")

    user, err := client.GetCurrentUser()
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Current user: %+v\n", user)
}
```

--------------------------------

### Multi-Level IVR System Example

Source: https://github.com/kong/kongctl/blob/main/test/e2e/scenarios/portal/visibility/testdata/apis/voice/docs/ncco.md

An example demonstrating how to build a multi-level IVR system using NCCO actions like 'talk', 'input', and 'connect'. This example shows handling user selections and routing calls.

```APIDOC
## Building Complex Call Flows - Multi-Level IVR System

### Description
This section provides an example of a multi-level IVR system. It uses `talk` and `input` actions to guide the user and `connect` to route calls based on user input.

### Initial IVR Menu
```json
[
  {
    "action": "talk",
    "text": "Welcome to ACME Bank. For account balance, press 1. For transactions, press 2. For customer service, press 3.",
    "bargeIn": true
  },
  {
    "action": "input",
    "maxDigits": 1,
    "timeOut": 10,
    "eventUrl": ["https://example.com/ivr/main-menu"]
  }
]
```

### Handling User Selection (Example Python Backend)

#### Main Menu Handler (`/ivr/main-menu`)
```python
@app.route('/ivr/main-menu', methods=['POST'])
def main_menu():
    selection = request.json['dtmf']
    
    if selection == '1':
        # Account Balance
        ncco = [
            {
                "action": "talk",
                "text": "Please enter your 4-digit PIN."
            },
            {
                "action": "input",
                "maxDigits": 4,
                "timeOut": 10,
                "eventUrl": ["https://example.com/ivr/verify-pin"]
            }
        ]
    elif selection == '2':
        # Transactions
        ncco = [
            {
                "action": "talk",
                "text": "For recent transactions, press 1. For pending transactions, press 2."
            },
            {
                "action": "input",
                "maxDigits": 1,
                "eventUrl": ["https://example.com/ivr/transactions"]
            }
        ]
    elif selection == '3':
        # Customer Service
        ncco = [
            {
                "action": "talk",
                "text": "Connecting you to the next available agent."
            },
            {
                "action": "stream",
                "streamUrl": ["https://example.com/hold-music.mp3"],
                "loop": 0
            },
            {
                "action": "connect",
                "endpoint": [{
                    "type": "phone",
                    "number": "447700900123"
                }],
                "eventUrl": ["https://example.com/ivr/agent-connected"]
            }
        ]
    else:
        # Invalid selection
        ncco = [
            {
                "action": "talk",
                "text": "Invalid selection. Please try again."
            },
            # Loop back to main menu
            {
                "action": "input",
                "maxDigits": 1,
                "eventUrl": ["https://example.com/ivr/main-menu"]
            }
        ]
    
    return jsonify(ncco)
```
```

--------------------------------

### Namespace-Based Sync Examples

Source: https://github.com/kong/kongctl/blob/main/internal/cmd/root/verbs/help/templates/sync.md

Shows how to perform synchronization operations scoped to specific namespaces using configuration files.

```bash
kongctl sync -f team-alpha-config.yaml
# Only syncs namespace: team-alpha
```

```bash
kongctl sync -f team-configs/
# Syncs each namespace independently
```

--------------------------------

### API Response Example

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/external/platform/snippets/api-quickstart.md

This is an example of a successful response from the API, indicating the service status and version.

```json
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "2.1.0"
}
```

--------------------------------

### Basic Apply from Directory

Source: https://github.com/kong/kongctl/blob/main/internal/cmd/root/verbs/help/templates/apply.md

Applies all configuration files within a specified directory, processing recursively.

```bash
# Apply from directory
kongctl apply -f ./configs/
```

--------------------------------

### Install GitHub Extensions

Source: https://github.com/kong/kongctl/blob/main/docs/extensions.md

Commands for installing extensions directly from GitHub repositories, with optional version tagging.

```sh
kongctl install extension owner/repo
kongctl install extension owner/repo@v0.1.0
kongctl install extension owner/repo@0.1.0
```

--------------------------------

### Control Plane Resource Example

Source: https://github.com/kong/kongctl/blob/main/skills/kongctl-declarative/references/resources.md

A basic example of a `control_planes` resource configuration, including common fields.

```yaml
control_planes:
  - ref: cp-main
    name: "my-control-plane"
    cluster_type: "CLUSTER_TYPE_CONTROL_PLANE"
```

--------------------------------

### YAML Configuration with References

Source: https://github.com/kong/kongctl/blob/main/docs/contributor/declarative-resource-implementation-guide.md

Example demonstrating references within YAML configurations, including references to sibling resources using the !ref tag.

```yaml
foos:
  - ref: foo-a
    name: Foo A

foo_children:
  - ref: child-a
    foo: foo-a
    slug: page-1
    parent_child_ref: !ref another-child#id  # Reference to sibling
```

--------------------------------

### Call Not In Progress Error Example

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/portal/apis/example-api/documents/errors.md

Example of a 'Call Not In Progress' error. Indicates that a call cannot be modified because it is not in a modifiable state.

```json
{
  "type": "INVALID_REQUEST",
  "title": "Invalid Request",
  "detail": "Call is not in progress"
}
```

--------------------------------

### SMS API Missing Parameters Error Example

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/portal/apis/sms/docs/errors.md

An example of an error response indicating missing required parameters.

```json
{
  "status": "2",
  "error-text": "Missing to param"
}
```

--------------------------------

### Start a New Game

Source: https://github.com/kong/kongctl/blob/main/test/e2e/scenarios/deck/sync/testdata/api/docs/getting-started.md

Use this cURL command to start a new game. Ensure you include your authorization token.

```curl
curl -X POST https://api.example.com/games \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Explaining Resource Structure

Source: https://github.com/kong/kongctl/blob/main/skills/kongctl-declarative/references/troubleshooting.md

Use `kongctl explain` to confirm accepted fields and their YAML placement for a given resource path.

```bash
kongctl explain <resource-path> --extended -o text
```

--------------------------------

### Applying Configuration Updates with Overlays

Source: https://github.com/kong/kongctl/blob/main/test/e2e/scenarios/GETTING_STARTED.md

This snippet demonstrates how to use overlays to test updates to a portal's description. It shows the overlay file content and the kongctl step configuration to apply the update.

```yaml
portals:
  - ref: test-portal
    description: "Updated portal description"
```

```yaml
- name: 003-update-portal
  inputOverlayDirs:
    - ./config/overlays/update-description
  commands:
    - name: apply-update
      run:
        - apply
        - -f
        - "{{ .workdir }}/portal.yaml"
        - --auto-approve
      assertions:
        - select: >-
            plan.changes[?resource_type=='portal' &&
                          resource_ref=='test-portal'] | [0]
          expect:
            fields:
              action: UPDATE
```

```yaml
- name: 004-verify-update
  skipInputs: true
  commands:
    - name: get-portals
      run: [get, portals, -o, json]
      assertions:
        - select: "[?name=='My Test Portal'] | [0]"
          expect:
            fields:
              description: "Updated portal description"
```

--------------------------------

### Explicit Planning with Kongctl

Source: https://github.com/kong/kongctl/blob/main/docs/declarative.md

Illustrates the two-phase execution for explicit planning: first generating a plan artifact, then applying it.

```shell
# Phase 1: Generate plan artifact
kongctl plan -f config.yaml --output-file plan.json

# Phase 2: Execute plan artifact (can be done later)
kongctl apply --plan plan.json
```

--------------------------------

### Event Webhook - Input Event Example

Source: https://github.com/kong/kongctl/blob/main/test/e2e/scenarios/portal/visibility/testdata/apis/voice/docs/webhooks.md

Example payload for an Input Event (DTMF collection) received by the Event Webhook.

```APIDOC
## Event Webhook - Input Event

### Description
This event is triggered when DTMF tones are collected during a call, typically after an `input` action in an NCCO.

### Method
POST (as configured)

### Endpoint
[Your configured Event Webhook URL]

### Request Body
```json
{
  "dtmf": "string (collected digits)",
  "timed_out": "boolean",
  "uuid": "string (UUID)",
  "conversation_uuid": "string (UUID)",
  "timestamp": "string (ISO 8601 format)"
}
```

### Request Example
```json
{
  "dtmf": "1234",
  "timed_out": false,
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "timestamp": "2020-01-01T12:00:00.000Z"
}
```
```

--------------------------------

### Event Webhook - Call State Event Example

Source: https://github.com/kong/kongctl/blob/main/test/e2e/scenarios/portal/visibility/testdata/apis/voice/docs/webhooks.md

Example payload for a Call State Event received by the Event Webhook.

```APIDOC
## Event Webhook - Call State Event

### Description
This event is triggered for significant changes in the call's lifecycle, such as initiation, ringing, answering, or completion.

### Method
POST (as configured)

### Endpoint
[Your configured Event Webhook URL]

### Request Body
```json
{
  "from": "string",
  "to": "string",
  "uuid": "string (UUID)",
  "conversation_uuid": "string (UUID)",
  "status": "string (e.g., started, ringing, answered, complete)",
  "direction": "string (outbound | inbound)",
  "timestamp": "string (ISO 8601 format)"
}
```

### Request Example
```json
{
  "from": "447700900001",
  "to": "447700900000",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "status": "started",
  "direction": "outbound",
  "timestamp": "2020-01-01T12:00:00.000Z"
}
```
```

--------------------------------

### Setup and Run Debug Script Extension

Source: https://github.com/kong/kongctl/blob/main/docs/examples/extensions/script/README.md

This snippet shows how to make the debug script extension executable, link it to kongctl, and then run the two new commands it provides.

```sh
chmod +x docs/examples/extensions/script/kongctl-ext-debug
kongctl link extension docs/examples/extensions/script
kongctl get debug-info --example
kongctl print-debug-info --example
```

--------------------------------

### 404 Not Found Example

Source: https://github.com/kong/kongctl/blob/main/test/e2e/scenarios/portal/visibility/testdata/apis/example-api/documents/errors.md

Example of a 404 Not Found error response, typically when a requested resource, like a call UUID, does not exist.

```APIDOC
#### 404 Not Found

Resource doesn't exist.

**Common Causes**:
- Invalid call UUID
- Call already ended
- Wrong endpoint URL

**Example**:
```json
{
  "type": "NOT_FOUND",
  "title": "Not Found",
  "detail": "Call 63f61863-4a51-4f6b-86e1-46edebcf9356 not found"
}
```
```

--------------------------------

###  kongctl Extension Command Path Examples

Source: https://github.com/kong/kongctl/blob/main/docs/extensions.md

Illustrates how an extension can contribute custom command paths to the kongctl CLI.

```yaml
command_paths:
  - path:
      - name: get
      - name: debug-info
  - path:
      - name: print-debug-info
```

--------------------------------

### Execute Create/Update Inline with kongctl apply

Source: https://github.com/kong/kongctl/blob/main/skills/kongctl-declarative/references/commands.md

Execute create and update operations immediately using `kongctl apply`. Use `--dry-run` for a text preview before actual execution.

```bash
kongctl apply -f <path> --dry-run -o text
```

```bash
kongctl apply -f <path> -o text
```

--------------------------------

### Invalid Number Format Error Example

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/portal/apis/example-api/documents/errors.md

Example of an 'Invalid Number Format' error. Requires numbers to be in E.164 format.

```json
{
  "type": "INVALID_REQUEST",
  "title": "Invalid Request",
  "detail": "Number must be in E.164 format"
}
```

--------------------------------

### 403 Forbidden Example

Source: https://github.com/kong/kongctl/blob/main/test/e2e/scenarios/portal/visibility/testdata/apis/example-api/documents/errors.md

Example of a 403 Forbidden error response, indicating the request is not allowed due to insufficient permissions or feature restrictions.

```APIDOC
#### 403 Forbidden

Request not allowed.

**Common Causes**:
- Insufficient permissions
- Feature not enabled for account
- Restricted destination

**Example**:
```json
{
  "type": "FORBIDDEN",
  "title": "Forbidden",
  "detail": "Calls to premium numbers are not allowed"
}
```
```

--------------------------------

### Empty Configuration Sync Examples

Source: https://github.com/kong/kongctl/blob/main/internal/cmd/root/verbs/help/templates/sync.md

Illustrates how to use `kongctl sync` with an empty configuration to delete managed resources within a namespace. It's recommended to perform a dry run first.

```bash
echo 'apis: []' | kongctl sync -f -
```

```bash
echo 'apis: []' | kongctl sync -f - --dry-run
```

--------------------------------

### Voice API Call Request Examples

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/portal/apis/example-api/documents/errors.md

Examples of Voice API call requests, demonstrating the use of 'answer_url' and inline 'ncco'.

```python
# Option 1: Using answer_url
call_request = {
    "to": [{"type": "phone", "number": "447700900000"}],
    "from": {"type": "phone", "number": "447700900001"},
    "answer_url": ["https://example.com/answer"]
}

# Option 2: Using inline NCCO
call_request = {
    "to": [{"type": "phone", "number": "447700900000"}],
    "from": {"type": "phone", "number": "447700900001"},
    "ncco": [{"action": "talk", "text": "Hello"}]
}
```

--------------------------------

### Deploy Platform Configuration

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/external/platform/README.md

Use this command to deploy the portal and API configurations. Ensure you are in the platform directory.

```bash
cd platform/
kongctl apply portal.yaml api.yaml
```

--------------------------------

### 404 Not Found Error Example

Source: https://github.com/kong/kongctl/blob/main/docs/examples/declarative/portal/apis/example-api/documents/errors.md

Example of a 404 Not Found error response. Occurs when a requested resource, like a call UUID, does not exist.

```json
{
  "type": "NOT_FOUND",
  "title": "Not Found",
  "detail": "Call 63f61863-4a51-4f6b-86e1-46edebcf9356 not found"
}
```

--------------------------------

### Foo Resource Planner Implementation

Source: https://github.com/kong/kongctl/blob/main/docs/contributor/declarative-resource-implementation-guide.md

Defines the `fooPlannerImpl` struct and its constructor, responsible for planning changes to Foo resources based on desired and current states.

```go
package planner

import (
    "context"
    "github.com/kong/kongctl/internal/declarative/resources"
    "github.com/kong/kongctl/internal/declarative/state"
)

type fooPlannerImpl struct {
    planner   *Planner
    resources *resources.ResourceSet
}

func newFooPlanner(planner *Planner, resourceSet *resources.ResourceSet) *fooPlannerImpl {
    return &fooPlannerImpl{
        planner:   planner,
        resources: resourceSet,
    }
}

func (f *fooPlannerImpl) GetDesiredFoos(namespace string) []resources.FooResource {
    var result []resources.FooResource
    for _, foo := range f.resources.Foos {
        if foo.Kongctl == nil || foo.Kongctl.Namespace == nil {
            continue
        }
        if *foo.Kongctl.Namespace == namespace {
            result = append(result, foo)
        }
    }
    return result
}

func (f *fooPlannerImpl) PlanChanges(ctx context.Context, plannerCtx *Config, plan *Plan) error {
    namespace := plannerCtx.Namespace

    // Plan parent foos
    if err := f.planner.planFooChanges(ctx, plannerCtx, f.GetDesiredFoos(namespace), plan); err != nil {
        return err
    }

    // Plan child resources if any
    // if err := f.planner.planFooChildrenChanges(ctx, plannerCtx, ...); err != nil {
    //     return err
    // }

    return nil
}
```