Give Feedback

pydo.endpoint_versions.create_promotion()

Generated on 6 Nov 2026 from pydo version v0.45.0

Copy page as Markdown View page as Markdown

Usage

client.endpoint_versions.create_promotion(
    endpoint_id="1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13",
    body={
        "version_id": "1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13.v1",
    },
)

Returns JSON Raises HttpResponseError

Description

Copies a live version’s configuration into a new, higher-numbered head version and sets promoted_from_version_number. Existing versions never change. Only the endpoint owner may promote. An inaccessible endpoint returns 404 endpoint_not_found, and a deleted, unknown, or different endpoint’s version returns 404 endpoint_version_not_found. The new version always has a new identity and number, even for identical contents; deleted identities are never resurrected. Head replacement does not change the endpoint’s Insights consent, which applies to every version.

Parameters

endpoint_id string required

Example: 1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13

Endpoint UUID only. Malformed IDs or full URNs return 400 invalid_endpoint_id.

version_id string required

Example: 1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13.v1

The endpoint UUID followed by .v and its version number, without a URN prefix. The UUID is lowercase and hyphenated. The number is from 1 through 4294967295, in decimal without signs or leading zeros. A bare UUID is not a version ID.

Request Sample

Show Request Sample

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "version_id": "1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13.v1"
}

resp = client.endpoint_versions.create_promotion(endpoint_id="1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13", body=req)

Response Example

Show Response Example

{
  "endpoint": {
    "id": "1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13",
    "name": "support-agent",
    "actor_id": "alice",
    "is_default": false,
    "insights": {
      "metrics": null,
      "logs": true,
      "traces": false
    },
    "mcp_url": "https://nyc3.actions.do-ai.run/mcp/endpoint/1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13",
    "created_at": "2026-10-15T14:00:00Z",
    "updated_at": "2026-10-16T14:00:00Z",
    "head_version": {
      "id": "1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13.v3",
      "endpoint_id": "1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13",
      "version_number": 3,
      "promoted_from_version_number": 1,
      "name": "support-agent",
      "actor_id": "alice",
      "tools": {
        "references": [
          {
            "kind": "SESSION_TOOL_REFERENCE_KIND_TOOL",
            "name": "exa_web_search",
            "version": "1"
          }
        ]
      },
      "policy": {
        "defaultAction": "ask",
        "rules": [
          {
            "tool": "exa_web_search@1",
            "match": {},
            "action": "allow"
          }
        ]
      },
      "config": {
        "preloadTools": [
          "exa_web_search"
        ],
        "outputViews": {
          "exa_web_search": "titles-and-urls"
        },
        "customInstructions": "Prefer primary sources and cite URLs."
      },
      "network": {
        "vpcUuid": "5a4981aa-9653-4bd1-bef5-d6bff52042e4",
        "region": "nyc3"
      },
      "mcp_url": "https://nyc3.actions.do-ai.run/mcp/endpoint/1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13/version/3b3c9f0e-1a4d-4e5f-8a7b-6c5d4e3f2a1b",
      "created_at": "2026-10-16T14:00:00Z",
      "updated_at": "2026-10-16T14:00:00Z"
    }
  },
  "version": {
    "id": "1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13.v3",
    "endpoint_id": "1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13",
    "version_number": 3,
    "promoted_from_version_number": 1,
    "name": "support-agent",
    "actor_id": "alice",
    "tools": {
      "references": [
        {
          "kind": "SESSION_TOOL_REFERENCE_KIND_TOOL",
          "name": "exa_web_search",
          "version": "1"
        }
      ]
    },
    "policy": {
      "defaultAction": "ask",
      "rules": [
        {
          "tool": "exa_web_search@1",
          "match": {},
          "action": "allow"
        }
      ]
    },
    "config": {
      "preloadTools": [
        "exa_web_search"
      ],
      "outputViews": {
        "exa_web_search": "titles-and-urls"
      },
      "customInstructions": "Prefer primary sources and cite URLs."
    },
    "network": {
      "vpcUuid": "5a4981aa-9653-4bd1-bef5-d6bff52042e4",
      "region": "nyc3"
    },
    "mcp_url": "https://nyc3.actions.do-ai.run/mcp/endpoint/1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13/version/3b3c9f0e-1a4d-4e5f-8a7b-6c5d4e3f2a1b",
    "created_at": "2026-10-16T14:00:00Z",
    "updated_at": "2026-10-16T14:00:00Z"
  },
  "mcp_url": "https://nyc3.actions.do-ai.run/mcp/endpoint/1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13",
  "version_mcp_url": "https://nyc3.actions.do-ai.run/mcp/endpoint/1b4d4e0f-9a7c-4d5b-8f3c-2a6e6e8f0a13/version/3b3c9f0e-1a4d-4e5f-8a7b-6c5d4e3f2a1b"
}

More Information

See /v2/action-gateway/endpoints/{endpoint_id}/versions:promote in the API reference for additional detail on responses, headers, parameters, and more.