Create an integration

You can build a custom Guild integration for any HTTP-accessible service. You don’t need to be a Guild engineer or wait for first-party support — if your service has an API, you can connect it. Create a custom integration when:

You need an integration for a private or internal service (e.g., an internal deployment platform, a self-hosted tool)
A first-party integration doesn’t exist yet for a public service you use
You want to customize how agents interact with a service beyond what a first-party integration offers

How it works

A custom integration is a versioned package that tells the Guild runtime how to proxy HTTP requests to your service on behalf of agents. You define the endpoints, authentication method, and request/response schemas. Once published, agents can call your integration’s tools exactly like any first-party integration.

Agent → Guild runtime → Integration proxy → Your service API
                ↓
        Handles auth, rate limiting,
        credential injection

The runtime injects credentials automatically, so agents never see raw API keys or tokens.

Creating an integration

You can create integrations from the Guild UI or entirely from the CLI.

Guild validates all integration endpoint URLs to prevent server-side request forgery (SSRF). This applies to the base URL, MCP server URL, OAuth install URL (--install-url), and OAuth token URL (--token-url). Private network ranges, loopback addresses (such as localhost or 127.0.0.1), and internal DNS names are blocked.The same protection applies to JSON schemas. Every $ref must point inside its own document, beginning with #. Guild will not fetch a reference from anywhere else, so a schema that points at a URL or a separate file is rejected when it is parsed. This covers OpenAPI specs, agent input schemas, and schemas served by an MCP server.For local development and testing, expose your local service using a tunneling tool such as ngrok or Localtunnel and use the public URL it provides.

1. Create the integration

guild integration create my-service \
  --base-url https://api.example.com \
  --auth-scheme api-key \
  --description "Connect to the Acme API"

For OAuth services, provide the OAuth configuration:

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"

Some OAuth servers require the client credentials to be sent as an HTTP Basic Authentication header on the token exchange request instead of in the POST body. The CLI has no flag for this — set Token Auth Method to Basic on the integration in the web interface. See Token Auth Method below.Use --public to make the integration visible to all users. By default it is private to your account.The command also creates a draft version automatically.

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.

2. Define operations

Add operations (endpoints) to your draft version. Each operation becomes a tool that agents can call.Add operations manually:

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

guild integration operation create myorg~my-service \
  --operation get_user \
  --method GET \
  --path /users/{id} \
  --summary "Get a user by ID"

Or import from an OpenAPI 3.0 or 3.1 spec:

guild integration operation create myorg~my-service --openapi ./openapi.yaml

When importing from an OpenAPI spec, Guild reads a request body from application/json, application/json-patch+json, application/x-www-form-urlencoded, or multipart/form-data. A response schema is read from the first three; multipart/form-data is accepted for request bodies only.Guild handles HTTP redirect response codes as follows:

Temporary redirects (302, 303, 307): the operation is kept. The response schema is parsed as unknown because the redirect does not define the final response shape.
Permanent redirects (301, 308): the operation is skipped. These codes indicate deprecated or moved endpoints.

An operation is skipped when its request body uses none of the content types above, or when it declares no success response. Skipped operations are listed in the endpoint-generator build step, so check there — and in the CLI output when you import from the command line — to see what did not come through.

OpenAPI specifications must be fully self-contained. Guild does not support external $ref pointers — references to external URLs, local file paths, or documents outside the spec. Importing a spec that contains an external $ref fails with a parsing error. This restriction protects against server-side request forgery (SSRF).

You can optionally provide JSON schema files for request and response bodies:

guild integration operation create myorg~my-service \
  --operation create_user \
  --method POST \
  --path /users \
  --summary "Create a new user" \
  --input-body-schema ./create-user-input.json \
  --output-body-schema ./create-user-output.json

3. Build and publish

# Build (validate) and assign a version number
guild integration version build myorg~my-service --version-number 1.0.0

# Publish the built version
guild integration version publish myorg~my-service --version-number 1.0.0

Version numbers must be strictly increasing — you cannot publish 1.0.0 after 1.1.0.

4. Test

Test an operation against the live API:

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

Pass path parameters, query parameters, and request bodies as JSON:

guild integration version test myorg~my-service \
  --operation get_user \
  --account my-account \
  --input-path '{"id": "user-123"}'

Testing a version against a credential owned by an account — an organization’s shared credential, for example — requires you to be an admin of that account. Anyone else gets a 403 with “Only admins can test integrations with credentials for this account.”

5. Connect credentials

guild integration connect myorg~my-service --token <api-key>

Omit --token for an interactive prompt. Use --owner to connect credentials for an organization account.

6. Configure webhooks (optional)

Pass webhook event definitions as JSON when creating or updating the integration:

guild integration create my-service \
  --base-url https://api.example.com \
  --auth-scheme api-key \
  --webhook-events '[{"event": "push"}, {"event": "pull_request", "actions": ["opened", "closed"]}]'

Or update an existing integration:

guild integration update myorg~my-service \
  --webhook-events '[{"event": "deploy", "actions": ["started", "completed", "failed"]}]'

See Webhook format below for delivery requirements.

1. Create the integration

Go to the Integration Hub in the Guild UI and click Create Integration. Provide:

Name — a unique identifier for your integration
Description — what the integration connects to and what it does
Protocol — choose REST or MCP:
- REST — the base URL of the target API. Optionally add Additional headers as header name and value pairs to send static headers on every proxied request, such as a vendor-specific API version header.
- MCP — the MCP server URL. Optionally add Additional headers as header name and value pairs to send static headers on every proxied request.
Authentication — how the target service authenticates requests

To change the headers on an existing integration, open it and use Edit Protocol Configuration. The base URL or MCP server URL is fixed when the integration is created and cannot be changed there.Authentication types:

Type	Use for
API key	Services that authenticate with a static token or API key
OAuth	Services that use OAuth 2.0 flows (Guild manages the token lifecycle)
OAuth M2M	Services that use the OAuth 2.0 client credentials flow

When you select OAuth M2M, configure these fields:

Field	Type	Required	Description
`token_url`	string	Yes	The OAuth token exchange endpoint. Example: `https://api.example.com/oauth/token`.
`scopes`	array of strings	Yes	OAuth scopes the client registers for. Example: `["read", "write"]`.
`extra_auth_params`	object	No	Additional parameters sent with the token request. Example: `{"response_mode": "query"}`.

OAuth M2M is configured through the web interface. guild integration create --auth-scheme accepts only api-key and oauth.

Token Auth Method

For OAuth and OAuth M2M alike, Token Auth Method (token_auth_method) controls how the client credentials reach the token endpoint:

Value	API value	Behavior
`Body` (default)	`BODY`	Client credentials are sent in the POST body on token exchange
`Basic`	`BASIC`	Client credentials are sent as an HTTP Basic Auth header on token exchange

Set this to Basic only when the token endpoint requires it — most services use Body.

Use PKCE

For OAuth, you can also toggle Use PKCE:

Value	Behavior
Enabled (default)	Guild sends a PKCE (Proof Key for Code Exchange) code challenge and verifier during the OAuth flow
Disabled	Guild omits PKCE from the OAuth flow

Leave Use PKCE enabled — most modern providers support it. Disable it only for providers that reject PKCE, such as LinkedIn. The integration’s configuration view shows whether PKCE is enabled or disabled.

2. Create a version

Creating the integration automatically creates a draft version 1. Each integration can have multiple versions that follow semantic versioning.

3. Define endpoints

Each endpoint maps to an operation on the target service. An endpoint definition includes:

Field	Description
Operation name	A unique identifier for this endpoint (becomes the tool name agents see)
HTTP method	`GET`, `POST`, `PUT`, `PATCH`, or `DELETE`
Path	The URL path on the target service (appended to the base URL)
Description	What the endpoint does — shown to LLMs when choosing tools

You can define endpoints in three ways:

Manually — add endpoints one at a time in the UI
From an OpenAPI specification — upload an OpenAPI 3.0 or 3.1 spec (YAML or JSON) and Guild generates endpoint definitions automatically
Copy from a previous version — carry forward endpoints from an earlier version and modify as needed

OpenAPI specifications must be fully self-contained. Guild does not support external $ref pointers — references to external URLs, local file paths, or documents outside the spec. Uploading a spec that contains an external $ref fails with a parsing error. This restriction protects against server-side request forgery (SSRF).

4. Build and publish

Once your endpoints are defined:

Build — Guild validates the configuration and assigns the semver you specified. Build status is tracked as a job.
Publish — the version becomes available for agents to use in workspaces.

Version numbers must be strictly increasing — you cannot publish 1.0.0 after 1.1.0.

5. Test

Open the Versions tab on your integration and click any version row to open that version’s detail page. Anyone can view and test a published version — edit, build, publish, and delete actions appear only for the integration owner.From the version detail page, click Test to invoke endpoints interactively. You can set path parameters, query parameters, and a request body, then see the full response including status code, headers, and body.The path parameter, query parameter, and request body inputs are schema-aware JSON editors backed by the endpoint’s JSON Schema. Each editor provides:

Auto-completions for known properties
Hover documentation for fields
Real-time syntax linting and validation

Guild disables the Invoke button when any input field contains invalid JSON; blank fields are treated as valid. Schema validation warnings, such as a missing required property, are advisory and do not block Invoke.The test page shows credential connection status. A warning indicator means no account is connected — click Connect to add one. A green indicator confirms credentials are ready.

If an endpoint has no request or response schema defined, the endpoint detail shows: “No request or response schema is defined for this endpoint.”

6. Configure webhooks (optional)

If your service sends events to Guild, you can define which webhook events the integration supports. This is optional — skip this step if your integration is request-only. Once configured, workspace users can create event triggers that fire agents automatically when your service emits an event.Open the integration’s Configuration tab and click Configure webhooks in the Webhooks section. See Webhook format below for delivery requirements.

Endpoint URLs are frozen at first publish

An integration’s URLs stay editable while you are building and testing it, so you can correct a mistake before anyone can install it. That ends at the first publish.

Once any version of an integration has been published, its URLs can no longer be changed — the REST base URL, the MCP server URL, the GraphQL endpoint URL, and the OAuth install and token URLs. Attempting to change one is rejected.Guild injects credentials into outbound requests server-side, so a published integration that could be repointed would be able to send those credentials somewhere new. Set these URLs correctly before you publish the first version.

Request body encoding

For POST, PUT, and DELETE requests, the REST proxy sends the request body as JSON and sets Content-Type: application/json by default. To send a form-encoded body instead, add "Content-Type": "application/x-www-form-urlencoded" to the integration’s extra headers. When you set this header, the proxy preserves it and encodes the request body as URL-encoded form data rather than JSON.

Visibility states

An integration with no published version shows a Draft badge, and its tools are not available to agents. Publishing a version clears the badge and makes the tools importable.

Making an integration public

Integrations are private to your account by default. An integration must already have a published version before it can be made public — setting is_public on one that has none is rejected with 403 Forbidden. So the order is: create the integration, define operations and publish a version, then change visibility. From the CLI:

guild integration update myorg~my-service --public

From the UI, open the integration’s kebab menu and select Publish to Agent Hub. The item appears in one of three states:

State	Condition
Enabled	The integration has a committed version and you are an admin of the owning organization.
Disabled, “Commit a version first”	The integration has no committed version.
Disabled, “Org admin permission needed”	You are not an admin of the owning organization.

Once the integration is public, the menu shows View on Agent Hub in place of Publish to Agent Hub.

Moderation and discoverability

Guild can moderate a public integration to keep the Hub’s discovery surfaces trustworthy. Moderation changes where an integration appears; it does not delete it, and existing connections keep working. The state appears as moderation_state on the integration in API responses.

`moderation_state`	Ranked and curated lists	Keyword search and creator profile	Direct link
`ACTIVE`	Visible	Visible	Visible
`DEMOTED`	Hidden	Visible	Visible
`UNLISTED`, `DISABLED`, `TAKEN_DOWN`	Hidden	Hidden	Visible

Ranked and curated lists are the home feed shelves, Browse all, and Top Creators. A DEMOTED integration is dropped from those but stays findable by name and on your profile. At UNLISTED and below it leaves discovery entirely and is reachable only by direct link, by you, or through an existing connection. Only Guild operators can set or clear a moderation state — you cannot change your own. Contact support if you believe an integration has been moderated in error.

Webhook format

If your integration receives inbound webhooks, your service must send a JSON body matching this format:

{
  "event": "push",
  "action": "opened",
  "payload": { ... }
}

action is null for events that don’t have sub-actions. Each delivery must include these headers: X-Guild-Webhook-Signature A cryptographic signature that proves the delivery came from the integration and hasn’t been tampered with in transit. Guild rejects deliveries with a missing or invalid signature. Generate it as follows:

Take the raw request body as a string.
Hash it using HMAC-SHA256 with the webhook secret key.
Hex-encode the result and prefix it: sha256=<hex-encoded hash>
Set that as the value of the X-Guild-Webhook-Signature header.

Signing with Ed25519 instead When you configure the webhook you choose a signature algorithm: HMAC-SHA256 (above) or Ed25519. For Ed25519 you register a public key rather than a shared secret, and each delivery carries a second header: X-Guild-Webhook-Timestamp The POSIX timestamp of the request. Sign the timestamp concatenated with the raw request body, then hex-encode the signature into X-Guild-Webhook-Signature. Guild rejects deliveries whose timestamp is more than 5 minutes old. The public key must be exactly 64 hexadecimal characters — a 32-byte Ed25519 key. Guild rejects anything else with Ed25519 public key must be exactly 64 hexadecimal characters. X-Guild-Webhook-ID A unique identifier for each individual delivery (e.g., a UUID generated fresh per request). Guild uses this to detect and discard duplicate deliveries, which is important because many systems retry failed webhook requests. Content-Type Must be set to application/json. How the webhook URL is set up When a user connects the integration and wants to receive webhook events, Guild generates a unique webhook URL for that connection. The user registers this URL with the external service (usually on its webhook configuration page) so the service knows where to send deliveries. How the secret key is established During that same registration, the external service typically reveals a secret key. The user copies the secret back into Guild, which stores it with the connection and uses it to verify the X-Guild-Webhook-Signature on every incoming delivery. Deliveries with a missing or mismatched signature are rejected. Defining events Each event has a name and an optional list of actions. For example:

Event	Actions
`push`	(none)
`pull_request`	`opened`, `closed`, `merged`, `reopened`

Using your integration

Once published, your integration’s tools appear alongside first-party tools in the workspace. Agents import and use them the same way as any other service integration:

import { myServiceTools } from "@guildai-services/my-org~my-service";
import { llmAgent, guildTools } from "@guildai/agents-sdk";

export default llmAgent({
  description: "An agent that uses a custom integration.",
  tools: { ...myServiceTools, ...guildTools },
  systemPrompt: `You have access to the Acme API.
Use it to look up customer records when asked.`,
});

Connecting credentials

When a custom integration requires authentication, the workspace administrator configures credentials in Settings > Credentials at app.guild.ai, just like first-party integrations. If an agent invokes a tool from an unconfigured integration, Guild prompts the user to connect their account.

Webhooks

Custom integrations can also receive inbound webhooks from integrations. Configure a webhook URL in your integration, and external events will be routed to agents via event triggers.

Overview

Code & CI/CD

Communication

Project management

Testing

Productivity

Monitoring & observability

Data

Customer support

Sales & finance

Create an integration

How it works

Creating an integration

1. Create the integration

2. Define operations

3. Build and publish

4. Test

5. Connect credentials

6. Configure webhooks (optional)

1. Create the integration

Token Auth Method

Use PKCE

2. Create a version

3. Define endpoints

4. Build and publish

5. Test

6. Configure webhooks (optional)

Endpoint URLs are frozen at first publish

Request body encoding

Visibility states

Making an integration public

Moderation and discoverability

Webhook format

Using your integration

Connecting credentials

Webhooks

​How it works

​Creating an integration

​1. Create the integration

​2. Define operations

​3. Build and publish

​4. Test

​5. Connect credentials

​6. Configure webhooks (optional)

​1. Create the integration

​Token Auth Method

​Use PKCE

​2. Create a version

​3. Define endpoints

​4. Build and publish

​5. Test

​6. Configure webhooks (optional)

​Endpoint URLs are frozen at first publish

​Request body encoding

​Visibility states

​Making an integration public

​Moderation and discoverability

​Webhook format

​Using your integration

​Connecting credentials

​Webhooks

How it works

Creating an integration

1. Create the integration

2. Define operations

3. Build and publish

4. Test

5. Connect credentials

6. Configure webhooks (optional)

1. Create the integration

Token Auth Method

Use PKCE

2. Create a version

3. Define endpoints

4. Build and publish

5. Test

6. Configure webhooks (optional)

Endpoint URLs are frozen at first publish

Request body encoding

Visibility states

Making an integration public

Moderation and discoverability

Webhook format

Using your integration

Connecting credentials

Webhooks