> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Replace the secret bindings of a release alias

PUT https://api.runtype.com/v1/agents/{id}/aliases/{alias}/bindings
Content-Type: application/json

Replace the complete set of `{{secret:NAME}}` values executions resolve when they reach this agent through this pointer. A binding wins over the organization secret of the same name, so one preview per pull request can aim its HTTP tools at that pull request environment while the version content stays byte-identical to what `live` runs. Whole-set replacement: a name you stop sending stops resolving. Values are encrypted at rest and never returned. Names beginning RUNTYPE\_, PLATFORM\_, CLOUDFLARE\_ or INTERNAL\_ are refused because they are platform-resolved before the alias plane. A change bumps the alias revision and appends a `bind` receipt; an identical set writes nothing. Requires the same deploy scope as activating this alias.

Reference: https://docs.runtype.com/api-reference/runtype-api/agent-aliases/replace-the-secret-bindings-of-a-release-alias

## Authentication

- `Authorization` header (bearer token, required) — API key or Clerk session token

## Servers

- `https://api.runtype.com` (Production, default)
- `https://api.runtype-staging.com` (Staging)

## Request

### Path parameters

- `id` (string, required)
- `alias` (string, required)

### Headers

- `if-match` (string, optional) — The alias revision this write expects. Required on a `live` alias that already exists (428 without it) and refused with 412 when the stored revision has moved on. Optional on preview aliases and on the first `live` deployment, which has no revision yet.
- `idempotency-key` (string, optional) — Replay key. Repeating an activation with the same key returns the receipt the first call produced instead of moving the pointer twice.

### Body (application/json)

This endpoint expects an object.

- `bindings` (map from string to string, required) — The complete binding set, NAME to value. An empty object clears every binding.
- `reason` (string, optional) — Why this binding write happened, recorded on the receipt for humans.

## Response

### 200

Bindings replaced

- `alias` (string, required)
- `names` (list of string, required)
- `revision` (double, required)
- `changed` (boolean, optional) — Present on a write: false when the set was already identical and nothing moved.
- `receiptId` (string, optional, nullable) — The `bind` receipt this write appended, or null when it changed nothing.

## Errors

### 400 Bad Request Error

Binding name or value rejected

- `code` (enum, required) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
  - Allowed values: `alias_revision_required`
- `error` (string, required)
- `details` (list of V1AgentsIdAliasesAliasBindingsPutResponsesContentApplicationJsonSchemaDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 401 Unauthorized Error

Unauthorized

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 403 Forbidden Error

Insufficient permissions

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 404 Not Found Error

Alias or agent not found

- `code` (enum, required) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
  - Allowed values: `alias_revision_required`
- `error` (string, required)
- `agentId` (string, required)
- `alias` (string, required)
- `details` (list of V1AgentsIdAliasesAliasBindingsPutResponsesContentApplicationJsonSchemaDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 412 Precondition Failed Error

Alias revision mismatch

- `code` (enum, required) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
  - Allowed values: `alias_revision_required`
- `error` (string, required)
- `actual` (double, required, nullable)
- `expected` (double, required)
- `details` (list of V1AgentsIdAliasesAliasBindingsPutResponsesContentApplicationJsonSchemaDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 428 Precondition Error

If-Match required for the live alias

- `code` (enum, required) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
  - Allowed values: `alias_revision_required`
- `error` (string, required)
- `alias` (string, required)
- `details` (list of V1AgentsIdAliasesAliasBindingsPutResponsesContentApplicationJsonSchemaDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 500 Internal Server Error

Internal server error

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

## Types

### V1AgentsIdAliasesAliasBindingsPutResponsesContentApplicationJsonSchemaDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### ErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "alias": "string",
  "names": [
    "string"
  ],
  "revision": 1.1,
  "changed": true,
  "receiptId": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.runtype.com/v1/agents/id/aliases/alias/bindings"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.runtype.com/v1/agents/id/aliases/alias/bindings';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runtype.com/v1/agents/id/aliases/alias/bindings"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.runtype.com/v1/agents/id/aliases/alias/bindings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.runtype.com/v1/agents/id/aliases/alias/bindings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.runtype.com/v1/agents/id/aliases/alias/bindings', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.runtype.com/v1/agents/id/aliases/alias/bindings");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.runtype.com/v1/agents/id/aliases/alias/bindings")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```