{"command":{"effect":"write","timeoutSeconds":30,"inputSchema":{"type":"object","description":"Creates a session owned by your team, with a new session URN, and returns the MCP URL an agent connects to. tools selects the tools and toolbelts the session exposes, and policy decides which calls run, need approval, or are refused.\n\nSet config.cache to opt into result caching for all eligible tools or a specific list. Caching is off by default and must be enabled for the team.","properties":{"body":{"$ref":"#/definitions/session_create","examples":[{"name":"support-bot-alice","actorId":"alice","tools":["toolbelt:search-toolbelt@1","jira_create_issue"],"policy":{"defaultAction":"ask","rules":[{"tool":"toolbelt:search-toolbelt@1","match":{},"action":"allow"},{"tool":"jira_create_issue","match":{},"action":"ask"}]},"config":{"preloadTools":["exa_web_search"],"outputViews":{"exa_web_search":"titles-and-urls"}}}]}},"required":["body"],"additionalProperties":false,"definitions":{"session_create":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Required human-readable session name.","examples":["support-bot-alice"]},"actorId":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,64}$","description":"Optional actor binding: the user whose connections the session's tool calls use, matched against connection `user_id`. When set it must use the same alphabet as a connection's `user_id`, `[A-Za-z0-9._-]`, at most 64 characters; anything else is rejected with 400.","examples":["alice"]},"policy":{"description":"Optional tool-permission policy. Omitted asks before every call.","allOf":[{"$ref":"#/definitions/session_policy"}]},"tools":{"type":"array","description":"Omitted enables every tool. An explicit empty array enables no tools. Direct tools may be `<tool>` or `<tool>@<version>`, using provider-qualified tool slugs, and a pinned version must be the released one; toolbelt references must be version-pinned as `toolbelt:<belt-name>@<version>`.","items":{"type":"string"},"examples":[["toolbelt:search-toolbelt@1","jira_create_issue"]]},"config":{"type":"object","additionalProperties":true,"description":"Optional session options. config.preloadTools may contain concrete tool names (optionally version-pinned) and version-pinned toolbelt references. config.customInstructions is a string of at most 1000 characters. config.outputViews maps up to 100 tool slugs to the name of an output view to apply to that tool's results. config.cache opts eligible tools into result caching for this session.","properties":{"cache":{"$ref":"#/definitions/session_cache"}},"examples":[{"preloadTools":["exa_web_search"],"outputViews":{"exa_web_search":"titles-and-urls"},"customInstructions":"Prefer primary sources and cite URLs."}]},"network":{"description":"Product-level session network binding. When set, `vpc_uuid` must identify a VPC owned by the session's team.","allOf":[{"$ref":"#/definitions/session_network"}]},"insights":{"description":"Omitted when the request omitted insights or explicitly sent null.","allOf":[{"$ref":"#/definitions/session_insights"}]}},"description":"Describes a session to create."},"session_policy":{"type":["object","null"],"description":"Tool-permission policy of a session.","properties":{"defaultAction":{"type":"string","enum":["allow","ask","deny"],"description":"Action for calls no rule matches. Empty means ask; otherwise this must be allow, ask, or deny.","examples":["ask"]},"rules":{"type":"array","items":{"type":"object","properties":{"tool":{"type":"string","description":"Required. A tool slug, optionally `<tool_slug>@<version>`, or a toolbelt as `toolbelt:<name>@<version>`. When the session selects tools, the rule must name one of them.","examples":["exa_web_search"]},"match":{"type":"object","description":"Optional argument conditions, keyed by argument name; the rule applies only to calls whose arguments match.","additionalProperties":{"type":"string"},"examples":[{}]},"action":{"type":"string","enum":["allow","ask","deny"],"description":"Required: allow, ask, or deny.","examples":["allow"]}}},"description":"Rules for specific tools or toolbelts."}}},"session_cache":{"type":"object","additionalProperties":false,"description":"Opts the session into result caching. Omit config.cache to leave caching off. Set exactly one of tools or allEligible. Caching must also be enabled for the team. Tool selection and permission rules still apply to every call.","properties":{"tools":{"type":"array","maxItems":100,"description":"Provider-qualified tool slugs to cache. Every listed tool must resolve for the team and have a catalog cache policy, or session creation fails. Use slugs without version suffixes or toolbelt references. An empty array enables no tools.","items":{"type":"string"},"examples":[["exa_web_search"]]},"allEligible":{"type":"boolean","enum":[true],"description":"Enables caching for every called tool version with a catalog cache policy, including tools that become eligible after session creation. Do not combine with tools.","examples":[true]},"maxAgeSeconds":{"type":"integer","minimum":1,"maximum":300,"description":"Maximum cache lifetime in seconds for this session. Omit to use each tool's lifetime, up to 300 seconds. A smaller tool lifetime or provider response cache header can shorten it. Per-call max_age_seconds can require a fresher result but cannot increase this limit.","examples":[60]}},"oneOf":[{"required":["tools"]},{"required":["allEligible"]}],"examples":[{"allEligible":true,"maxAgeSeconds":60}]},"session_network":{"type":"object","description":"Attaches a session to a VPC.","properties":{"vpcUuid":{"type":"string","format":"uuid","description":"UUID of a VPC owned by your team, in a region that supports sessions.","examples":["5a4981aa-9653-4bd1-bef5-d6bff52042e4"]}}},"session_insights":{"type":"object","description":"Records which of a session's telemetry is sent to Insights.","properties":{"metrics":{"type":["boolean","null"],"description":"Accepted and stored for parity with the Insights schema.","examples":[true]},"logs":{"type":["boolean","null"],"description":"Whether the session's customer logs are sent to Insights.","examples":[true]},"traces":{"type":["boolean","null"],"description":"Whether the session's customer traces are sent to Insights.","examples":[false]}}}}},"name":"Create a Session","id":"digitalocean.sessions_create","example":{"body":{"name":"support-bot-alice"}},"maxRequests":1,"summary":false}}