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

# guild integration

> Build, version, and test custom integrations.

Build and manage custom integrations.

## Discovery and management

```bash theme={null}
guild integration list                        # List integrations
guild integration list --search "deploy"      # Search by name or description
guild integration list --published            # Only show published integrations
guild integration search <query>              # Search integrations
guild integration search <query> --sort newest  # Sort by: updated, newest, name
guild integration search <query> --published  # Only show published integrations
guild integration search <query> --limit 10 --offset 20  # Paginate results
guild integration get <id_or_name>            # Get integration details
```

## Creating and updating

`guild integration create` also registers an initial draft version and prints its ID, so you can define operations without running `guild integration version create` first.

```bash theme={null}
# Create a new integration with API key auth
guild integration create my-service \
  --base-url https://api.example.com \
  --auth-scheme api-key \
  --description "Connect to the Acme API"

# Create with OAuth
guild integration create my-oauth-service \
  --base-url https://api.example.com \
  --auth-scheme oauth \
  --install-url https://example.com/oauth/authorize \
  --token-url https://example.com/oauth/token \
  --client-id <id> --client-secret <secret> \
  --scopes "read,write"

# Update an existing integration
guild integration update myorg~my-service --description "Updated description"
```

<Note>
  Publishing freezes the endpoint URL, and the OAuth authorization and token URLs with it. Until the integration's first version is published, the owner can still change them — nothing is installed against the integration yet. Once a version is published, users install credentials against those URLs, so Guild refuses to let the owner repoint them at another server. The whole update is rejected with a `403`, not just the URL field, so a request that changes a URL alongside other settings saves none of them. To serve a different endpoint, create a new integration.
</Note>

<Warning>
  Guild validates the `--base-url`, `--install-url`, and `--token-url` values to prevent server-side request forgery (SSRF). Private network ranges, loopback addresses (such as `localhost` or `127.0.0.1`), and internal DNS names are blocked. For local development, expose your service using a tunneling tool such as [ngrok](https://ngrok.com) or [Localtunnel](https://theboroer.github.io/localtunnel-www/) and use the public URL.
</Warning>

## Connecting credentials

```bash theme={null}
guild integration connect myorg~my-service --owner <account>                  # Interactive prompt
guild integration connect myorg~my-service --owner <account> --token <value>  # Non-interactive
```

## versions

```bash theme={null}
guild integration version list <id_or_name>                 # List versions
guild integration version create <id_or_name>               # Create a draft version
guild integration version get <id_or_name>                  # Get latest version details
guild integration version get <id_or_name> --version-number 1.0.0

guild integration version build <id_or_name> --version-number 1.0.0   # Validate a draft
guild integration version publish <id_or_name> --version-number 1.0.0 # Publish a built version
```

## Operations (endpoints)

```bash theme={null}
# List operations on a version
guild integration operation list <id_or_name>
guild integration operation list <id_or_name> --version-number 1.0.0

# Add operations manually
guild integration operation create myorg~my-service \
  --operation list_users \
  --method GET \
  --path /users \
  --summary "List all users"

# Import operations from an OpenAPI spec
guild integration operation create myorg~my-service --openapi ./openapi.yaml
```

## Testing

```bash theme={null}
guild integration version test myorg~my-service \
  --operation list_users \
  --account my-account \
  --input-query '{"limit": 10}'
```