{"openapi":"3.1.0","info":{"title":"UpCloud (BYOK) API","version":"0.1.0","description":"UpCloud (BYOK) lets an AI assistant read your own UpCloud data through the UpCloud API with a key you supply (UpCloud API token (ucat_...)). Read-only: 7 tools (get_account, list_servers, get_server, list_storages, list_ip_addresses, list_networks, list_zones). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-upcloud.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-upcloud/docs"},"termsOfService":"https://connectorbay.com/byok-upcloud/terms"},"servers":[{"url":"https://byok-upcloud.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-upcloud/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_account":{"post":{"operationId":"get_account","summary":"Show the UpCloud account: remaining credits, user name and resource limits such as cores, memory, networks and storage. ","description":"Show the UpCloud account: remaining credits, user name and resource limits such as cores, memory, networks and storage. Use for \"What are my UpCloud resource limits\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_accountArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_servers":{"post":{"operationId":"list_servers","summary":"List cloud servers with title, hostname, zone, plan, cores, memory, state, tags and labels. Filter by state, tag or sear","description":"List cloud servers with title, hostname, zone, plan, cores, memory, state, tags and labels. Filter by state, tag or search text, and order or page the list. Use for \"Which UpCloud servers are stopped\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"enum":["started","stopped","maintenance","error"],"type":"string"},{"type":"null"}],"default":null,"description":"Only servers in this state.","title":"State"},"tag":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only servers with these tags, names separated by ',' or ':' (the two separators select any-of versus all-of matching).","title":"Tag"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Match name, title, uuid, zone, IP address, hostname, tag or template name.","title":"Search"},"order_by":{"anyOf":[{"enum":["title","zone","size","cores","memory","popularity"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by title, zone, size, cores, memory or popularity (use together with sort_by).","title":"Order By"},"sort_by":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction, asc or desc (use together with order_by).","title":"Sort By"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many servers to return.","title":"Limit"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"How many servers to skip.","title":"Offset"}},"title":"list_serversArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_server":{"post":{"operationId":"get_server","summary":"Get one server's configuration: state, plan, cores, memory, firewall flag, boot order, IP addresses, tags and labels. Co","description":"Get one server's configuration: state, plan, cores, memory, firewall flag, boot order, IP addresses, tags and labels. Console passwords are not requested. Use for \"Show details of UpCloud server 00798b85-efdc-41ca-8021-f6ef457b8531\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"uuid":{"description":"Server UUID from list_servers.","maxLength":64,"title":"Uuid","type":"string"}},"required":["uuid"],"title":"get_serverArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_storages":{"post":{"operationId":"list_storages","summary":"List storage devices (disks, backups, templates) with size in GB, tier, type, state, encryption flag and zone. Use for \"","description":"List storage devices (disks, backups, templates) with size in GB, tier, type, state, encryption flag and zone. Use for \"Which UpCloud storage devices do I have and how big are they\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_storagesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_ip_addresses":{"post":{"operationId":"list_ip_addresses","summary":"List IP addresses of the account with family, access (public, private, utility), floating flag, PTR record, server and z","description":"List IP addresses of the account with family, access (public, private, utility), floating flag, PTR record, server and zone. Use for \"Which public IPv4 addresses does my UpCloud account use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_ip_addressesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_networks":{"post":{"operationId":"list_networks","summary":"List SDN private and utility networks with their IP network ranges, DHCP and gateway settings and zone. Use for \"Which p","description":"List SDN private and utility networks with their IP network ranges, DHCP and gateway settings and zone. Use for \"Which private networks exist in my UpCloud account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"zone":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only networks in this zone id, for example 'fi-hel1'.","title":"Zone"}},"title":"list_networksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_zones":{"post":{"operationId":"list_zones","summary":"List the UpCloud zones (data centers) with description, id and whether they are public. Use for \"Which UpCloud zones can","description":"List the UpCloud zones (data centers) with description, id and whether they are public. Use for \"Which UpCloud zones can I deploy to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_zonesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}