---
title: "Create a binding"
method: POST
path: "/v1/agents/{agent_id}/bindings"
tags: ["Execution Intents"]
---

# Create a binding

`POST /v1/agents/{agent_id}/bindings`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/agents/{agent_id}/bindings`
- Auth: HTTP bearer

## Path parameters

- `agent_id` string, uuid, required

## Request body

- CreateBindingRequest
  - `name` string, required
  - `binding_type` 'http' | 'graphql' | 'postgres' | 'mysql' | 'redis' | 'grpc' | 'smtp' | 'cloud_sdk' | 's3' | 'custom', required: `postgres` / `mysql`: the connection URL must set `sslmode=verify-full` (Postgres) or `ssl-mode=VERIFY_IDENTITY` (MySQL) for TLS, or `sslmode=disable` / `ssl-mode=DISABLED` for a plaintext connection pinned to the resolved public IP. Any other mode, including leaving it unset (the drivers default to `prefer`), is refused with 400 when the binding is executed or tested.
  - `config` object
  - `guardrails` BindingGuardrails: Per-binding execution guardrails enforced at execute time.
    - `allowed_hosts` string[]: Host allowlist (trailing * wildcard supported). Empty = unrestricted at binding level.
    - `allowed_paths` string[]: Path allowlist for HTTP/GraphQL bindings.
    - `max_requests_per_minute` integer: Per-binding RPM; strictest of binding and agent limits wins. Denied executions do not count.
    - `max_duration_ms` integer: Upstream timeout cap for this binding.
    - `max_request_bytes` integer: Max serialized execute `params` size in bytes (default 256 KiB).
    - `max_response_bytes` integer: Max upstream response body bytes (default 1 MiB, hard cap 4 MiB).
    - `allowed_request_headers` string[]: Agent-supplied headers permitted in execute params (http, graphql, custom and grpc bindings); any other agent header is dropped. Defaults to content-type, accept, user-agent, idempotency-key. On grpc bindings the `grpc-*` and `connect-*` protocol headers (for example `Connect-Protocol-Version`, `grpc-timeout`) always pass, except names containing `auth` or `host`.
    - `allow_mutations` boolean: GraphQL only — when false, mutation operations return 403 guardrail_violation.
    - `allow_introspection` boolean: GraphQL only — when false, __schema/__type introspection is blocked.
    - `max_query_depth` integer: GraphQL max selection depth.
    - `max_aliases` integer: GraphQL max alias count.
    - `allowed_operations` string[]: GraphQL operation kinds allowed (query, mutation, subscription).
  - `credential` object: Legacy: inline credential value. Use credential_source for new integrations.
  - `credential_source` CredentialSource: Credential source — inline value (stored in __agent-keys) or live pointer to a vault secret (resolved at execution time).
    - `type` 'inline' | 'vault_ref', required
    - `value` object: For inline — the credential value object.
    - `vault_id` string, uuid: For vault_ref — the vault containing the referenced secret.
    - `path` string: For vault_ref — the secret path in the vault.

## Response `201`

Binding created

- BindingResponse
  - `id` string, uuid, required
  - `agent_id` string, uuid, required
  - `binding_type` 'http' | 'graphql' | 'postgres' | 'mysql' | 'redis' | 'grpc' | 'smtp' | 'cloud_sdk' | 's3' | 'custom', required
  - `name` string, required
  - `config` object
  - `guardrails` BindingGuardrails: Per-binding execution guardrails enforced at execute time.
    - `allowed_hosts` string[]: Host allowlist (trailing * wildcard supported). Empty = unrestricted at binding level.
    - `allowed_paths` string[]: Path allowlist for HTTP/GraphQL bindings.
    - `max_requests_per_minute` integer: Per-binding RPM; strictest of binding and agent limits wins. Denied executions do not count.
    - `max_duration_ms` integer: Upstream timeout cap for this binding.
    - `max_request_bytes` integer: Max serialized execute `params` size in bytes (default 256 KiB).
    - `max_response_bytes` integer: Max upstream response body bytes (default 1 MiB, hard cap 4 MiB).
    - `allowed_request_headers` string[]: Agent-supplied headers permitted in execute params (http, graphql, custom and grpc bindings); any other agent header is dropped. Defaults to content-type, accept, user-agent, idempotency-key. On grpc bindings the `grpc-*` and `connect-*` protocol headers (for example `Connect-Protocol-Version`, `grpc-timeout`) always pass, except names containing `auth` or `host`.
    - `allow_mutations` boolean: GraphQL only — when false, mutation operations return 403 guardrail_violation.
    - `allow_introspection` boolean: GraphQL only — when false, __schema/__type introspection is blocked.
    - `max_query_depth` integer: GraphQL max selection depth.
    - `max_aliases` integer: GraphQL max alias count.
    - `allowed_operations` string[]: GraphQL operation kinds allowed (query, mutation, subscription).
  - `is_active` boolean, required
  - `credential_set` boolean: Whether a credential is stored for this binding. The value itself is never returned.
  - `credential_source_type` 'inline' | 'vault_ref', nullable: How the credential is sourced — inline (HSM-encrypted copy) or vault_ref (live pointer).
  - `credential_vault_id` string, uuid, nullable: For vault_ref credentials — the vault containing the referenced secret.
  - `credential_path` string, nullable: For vault_ref credentials — the secret path in the referenced vault.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: Invalid request
- `403`: Insufficient permissions

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/5fa0918f3b41?raw)