Skip to Content

Publish an agent module

Publishes a self-contained JavaScript module and its manifest as the next immutable version.

POST
/v1/agents/{id}/versions

Publishes a self-contained JavaScript module and its manifest as the next immutable version. Source is stored by its SHA-256 digest without execution. The revision protects the draft read by the publisher; a stale revision returns 409. Publishing the same manifest, source, and definition again returns published false. The manifest controls the model, endpoints, integration grants, and action policy. Draft instructions and knowledge remain editable builder data; the hosted runtime reads instructions and tools from the published module.

Authorization

apiKey
headerx-api-key<token>

Path Parameters

id*string
Match^agt_[0-9a-hjkmnp-tv-z]{16,24}$

Request Body

application/json
  1. body
revision*string
Length1 <= length
bundle*

Response Body

PublishAgentResponse

application/json
  1. response
agent*
version*
published*boolean
Example Request
import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });

const result = await samva.agents.publishVersion({
  "id": "example",
  "revision": "example",
  "bundle": {
    "source": "example",
    "manifest": {
      "name": "example",
      "version": "example",
      "endpointIds": [
        "example"
      ],
      "integrations": [
        {
          "integrationId": "example",
          "tools": {
            "kind": "all"
          }
        }
      ],
      "policy": {
        "presets": [
          "example"
        ],
        "rules": [
          {
            "match": {},
            "decide": "run"
          }
        ]
      },
      "model": "standard",
      "reasoning": "auto",
      "workingHours": {
        "timeZone": "example",
        "ranges": [
          {
            "day": "monday",
            "opens": "example",
            "closes": "example"
          }
        ]
      },
      "takeoverTimeoutMinutes": 1,
      "tools": {},
      "skills": [
        "example"
      ],
      "events": [
        "example"
      ],
      "schedules": [
        "example"
      ]
    }
  }
});
Example Response
{
  "agent": {
    "id": "string",
    "name": "string",
    "setupJob": "support",
    "namespaceId": "string",
    "revision": "string",
    "draft": {
      "instructions": "string",
      "knowledge": "string",
      "knowledgeSourceIds": [
        "string"
      ],
      "endpointIds": [
        "string"
      ],
      "integrations": [
        {
          "integrationId": "string",
          "subject": "org",
          "tools": {
            "kind": "all"
          }
        }
      ],
      "policy": {
        "presets": [
          "string"
        ],
        "rules": [
          {
            "match": {
              "kind": "send",
              "effect": "read",
              "channel": "sms",
              "integration": "string",
              "tool": "string",
              "subject": "agent"
            },
            "note": "string",
            "decide": "run",
            "atLeast": null
          }
        ],
        "instructions": "string"
      },
      "model": "standard",
      "reasoning": "auto",
      "workingHours": {
        "timeZone": "string",
        "ranges": [
          {
            "day": "monday",
            "opens": "string",
            "closes": "string"
          }
        ]
      },
      "takeoverTimeoutMinutes": 1,
      "eventTriggers": [
        "string"
      ],
      "followUpTemplate": "string"
    },
    "publishedVersion": -9007199254740991,
    "publishedAt": "string",
    "pausedAt": "string",
    "creditsPausedAt": "string",
    "monthlySpendCapDollars": 0,
    "spend": {
      "month": "string",
      "spentDollars": 0,
      "capReachedAt": "string"
    },
    "createdAt": "string",
    "updatedAt": "string"
  },
  "version": {
    "agentId": "string",
    "version": -9007199254740991,
    "definition": {
      "instructions": "string",
      "knowledge": "string",
      "knowledgeSourceIds": [
        "string"
      ],
      "endpointIds": [
        "string"
      ],
      "integrations": [
        {
          "integrationId": "string",
          "subject": "org",
          "tools": {
            "kind": "all"
          }
        }
      ],
      "policy": {
        "presets": [
          "string"
        ],
        "rules": [
          {
            "match": {
              "kind": "send",
              "effect": "read",
              "channel": "sms",
              "integration": "string",
              "tool": "string",
              "subject": "agent"
            },
            "note": "string",
            "decide": "run",
            "atLeast": null
          }
        ],
        "instructions": "string"
      },
      "model": "standard",
      "reasoning": "auto",
      "workingHours": {
        "timeZone": "string",
        "ranges": [
          {
            "day": "monday",
            "opens": "string",
            "closes": "string"
          }
        ]
      },
      "takeoverTimeoutMinutes": 1,
      "eventTriggers": [
        "string"
      ],
      "followUpTemplate": "string"
    },
    "bundle": {
      "sha256": "string",
      "sizeBytes": 1,
      "manifest": {
        "name": "string",
        "version": "string",
        "knowledgeSourceIds": [
          "string"
        ],
        "endpointIds": [
          "string"
        ],
        "integrations": [
          {
            "integrationId": "string",
            "subject": "org",
            "tools": {
              "kind": "all"
            }
          }
        ],
        "policy": {
          "presets": [
            "string"
          ],
          "rules": [
            {
              "match": {
                "kind": "send",
                "effect": "read",
                "channel": "sms",
                "integration": "string",
                "tool": "string",
                "subject": "agent"
              },
              "note": "string",
              "decide": "run",
              "atLeast": null
            }
          ],
          "instructions": "string"
        },
        "model": "standard",
        "reasoning": "auto",
        "workingHours": {
          "timeZone": "string",
          "ranges": [
            {
              "day": "monday",
              "opens": "string",
              "closes": "string"
            }
          ]
        },
        "takeoverTimeoutMinutes": 1,
        "eventTriggers": [
          "string"
        ],
        "followUpTemplate": "string",
        "tools": {
          "property1": {
            "description": "string",
            "input": {
              "property1": "string",
              "property2": "string"
            },
            "approval": "run",
            "replay": "safe"
          },
          "property2": {
            "description": "string",
            "input": {
              "property1": "string",
              "property2": "string"
            },
            "approval": "run",
            "replay": "safe"
          }
        },
        "skills": [
          "string"
        ],
        "events": [
          "string"
        ],
        "schedules": [
          "string"
        ]
      }
    },
    "authoring": "builder",
    "publishedAt": "string",
    "modelFallback": {
      "from": "string",
      "to": "standard",
      "reason": "candidate",
      "since": "string"
    }
  },
  "published": true
}

Related documentation