Client libraries | StateWeave Docs
Your sandbox
Client libraries
If your agent already uses a vendor's client library, keep it. Give it the app's address and token instead of the real service's, and nothing else in your code changes. This page lists the one setting each library needs.
At a glance
Each library below, but Meta's, Stripe's, HubSpot's and GitHub's, was tested against a run served over HTTPS exactly as hosted runs are, with reads and writes: queries, lists across several pages, creates and updates. Stripe's and HubSpot's were tested the same way on a run served over plain HTTP. GitHub's were tested against the GitHub twin directly, with queries, creates and lists across several pages: Octokit, PyGithub and githubkit over plain HTTP and over HTTPS, and gh through a local socket, without TLS.
| App | Library | Tested | What to set |
|---|---|---|---|
| Slack | slack_sdk (Python) | 3.46.0 | base_url |
| Slack | @slack/web-api (Node) | 8.3.0 | slackApiUrl |
| google-api-python-client | 2.201.0 | discoveryServiceUrl and static_discovery=False | |
| googleapis (Node) | 189.0.0 | rootUrl | |
| Salesforce | simple-salesforce | 1.12.10 | instance_url , version |
| Salesforce | jsforce (Node) | 3.13.1 | instanceUrl , version |
| Shopify | ShopifyAPI (Python) | 12.7.0 | Session.myshopify_domain . GraphQL only. |
| Shopify | @shopify/admin-api-client | 2.0.1 | storeDomain |
| Zendesk | zenpy | 2.0.57 | subdomain and domain |
| Zendesk | node-zendesk | 6.0.1 | endpointUri |
| facebook-business (Python) | 26.0.2, against the twin | session.GRAPH | |
| Stripe | stripe (Python) | 16.0.1, over HTTP | base_addresses |
| HubSpot | hubspot-api-client (Python) | 13.0.0, over HTTP | host |
| GitHub | octokit (Node) | 5.0.5, against the twin | baseUrl |
| GitHub | gh (command line) | 2.101.0, without TLS | GH_HOST , GH_ENTERPRISE_TOKEN |
| GitHub | PyGithub (Python, community) | 2.10.0, against the twin | base_url |
| GitHub | githubkit (Python, community) | 0.17.1, against the twin | base_url |
The examples read the app as in Apps and credentials : app(name) is one of the run's apps and credential(name, kind) one of its tokens. The same works on what client.connect() returns in edit mode, or on run.apps in Python. In Node:
run.js
const
run = JSON.
parse
(
require
(
"fs"
).
readFileSync
(process.env.STATEWEAVE_RUN_FILE,
"utf8"
));
const
app = (name) => run.apps[name];
const
credential = (name, kind =
"user"
) => Object.
entries
(
app
(name).credentials).
find
(([label]) => label.
split
(
":"
)[
0
] === kind)[
1
];
The Node examples use await . In a CommonJS file, where require works, put them inside an async function.
From environment variables
With the STATEWEAVE_* variables instead (from sw sandbox connect p-… --env , a twin run's .env , or run.env ), build each endpoint from the app's address. STATEWEAVE_<APP>_URL has no trailing slash; Apps and credentials lists each app's API root.
Python
import
os
from
slack_sdk
import
WebClient slack =
WebClient
(token=os.environ[
"STATEWEAVE_SLACK_USER_TOKEN"
], base_url=os.environ[
"STATEWEAVE_SLACK_URL"
] +
"/api/"
)
Slack
from
slack_sdk
import
WebClient slack =
WebClient
(token=
credential
(
"slack"
,
"user"
), base_url=
app
(
"slack"
)[
"endpoints"
][
"web_api"
])
const
{ WebClient } =
require
(
"@slack/web-api"
);
const
slack =
new
WebClient
(
credential
(
"slack"
,
"user"
), { slackApiUrl:
app
(
"slack"
).endpoints.web_api });
The same setting serves Gmail, Calendar, Sheets and Drive. Python's library ships its own copy of each API description, so turn that off and point it at the app's. Node's takes the app's address as rootUrl , with a trailing slash.
from
google.oauth2.credentials
import
Credentials
from
googleapiclient.discovery
import
build gmail =
build
(
"gmail"
,
"v1"
, credentials=
Credentials
(
credential
(
"gmail"
)), discoveryServiceUrl=
app
(
"gmail"
)[
"endpoints"
][
"discovery"
], static_discovery=
False
)
const
{ google } =
require
(
"googleapis"
);
const
auth =
new
google.auth.
OAuth2
(); auth.
setCredentials
({ access_token:
credential
(
"gmail"
) });
const
gmail = google.
gmail
({ version:
"v1"
, auth, rootUrl:
app
(
"gmail"
).base_url +
"/"
});
For Sheets, list spreadsheets through Drive with the Sheets app's own token and its drive_discovery (Python) or the same rootUrl (Node).
Salesforce
Pass the version the app's rest_api names ( 68.0 ), not the library's default.
from
simple_salesforce
import
Salesforce sf =
Salesforce
(instance_url=
app
(
"salesforce"
)[
"endpoints"
][
"instance_url"
], session_id=
credential
(
"salesforce"
), version=
"68.0"
) accounts = sf.
query
(
"SELECT Id, Name FROM Account LIMIT 10"
)[
"records"
]
const
jsforce =
require
(
"jsforce"
);
const
conn =
new
jsforce.
Connection
({ instanceUrl:
app
(
"salesforce"
).endpoints.instance_url, accessToken:
credential
(
"salesforce"
), version:
"68.0"
, });
const
accounts = (
await
conn.
query
(
"SELECT Id, Name FROM Account LIMIT 10"
)).records;
Shopify
StateWeave's Shopify serves the GraphQL Admin API . The REST Admin API (paths such as /admin/api/2026-10/products.json ) answers 404 with the header x-twin-not-implemented: 1 , so use a library's GraphQL client.
import
shopify host =
app
(
"shopify"
)[
"base_url"
].
removeprefix
(
"https://"
)
# t-….app.stateweave.net
shop, _, domain = host.
partition
(
"."
) shopify.Session.myshopify_domain = domain
# the library appends this to the shop's name
session = shopify.
Session
(shop,
"2026-10"
,
credential
(
"shopify"
,
"app"
)) shopify.ShopifyResource.
activate_session
(session) result = shopify.
GraphQL
().
execute
(
"{ shop { name } orders(first: 10) { nodes { name } } }"
)
const
{ createAdminApiClient } =
require
(
"@shopify/admin-api-client"
);
const
shopify =
createAdminApiClient
({ storeDomain:
app
(
"shopify"
).base_url.
replace
(
"https://"
,
""
), apiVersion:
"2026-10"
, accessToken:
credential
(
"shopify"
,
"app"
), });
const
{ data } =
await
shopify.
request
(
"{ shop { name } orders(first: 10) { nodes { name } } }"
);
ShopifyAPI builds its own address. Given any shop name, it keeps the first label and adds .myshopify.com . Without Session.myshopify_domain set, your agent would call a real Shopify store, not StateWeave. Its REST resources ( shopify.Product , shopify.Order , …) use the REST Admin API and fail with ResourceNotFound .
Zendesk
from
zenpy
import
Zenpy host =
app
(
"zendesk"
)[
"base_url"
].
removeprefix
(
"https://"
)
# t-….app.stateweave.net
subdomain, _, domain = host.
partition
(
"."
) zendesk =
Zenpy
(subdomain=subdomain, domain=domain, oauth_token=
credential
(
"zendesk"
))
const
zendesk =
require
(
"node-zendesk"
);
const
client = zendesk.
createClient
({ endpointUri:
app
(
"zendesk"
).endpoints.rest_api.
replace
(
/\/$/
,
""
), token:
credential
(
"zendesk"
), oauth:
true
, });
Meta publishes no maintained WhatsApp messaging SDK, so messages go over plain HTTP (see WhatsApp ). Meta's business SDK, facebook-business , covers the account's objects: WhatsApp Business accounts, templates, phone numbers. Set the address it calls instead of graph.facebook.com on the session.
Python
from
facebook_business.api
import
FacebookAdsApi
from
facebook_business.adobjects.whatsappbusinessaccount
import
WhatsAppBusinessAccount
from
facebook_business.session
import
FacebookSession session =
FacebookSession
(access_token=
credential
(
"whatsapp"
,
"bot"
)) session.GRAPH =
app
(
"whatsapp"
)[
"base_url"
]
# no trailing slash, like https://graph.facebook.com
api =
FacebookAdsApi
(session, api_version=
"v26.0"
) templates =
WhatsAppBusinessAccount
(waba_id, api=api).
get_message_templates
(fields=[
"name"
,
"status"
])
waba_id is the WhatsApp Business account's id, found as in Apps and credentials . For anything the SDK has no class for, use api.call("POST", (phone_number_id, "messages"), params={…}) . This library was checked against the WhatsApp twin directly, over plain HTTP, not through a hosted run.
Stripe
Python
import
stripe base =
app
(
"stripe"
)[
"base_url"
] client = stripe.
StripeClient
(
credential
(
"stripe"
), base_addresses={
"api"
: base,
"files"
: base,
"connect"
: base,
"meter_events"
: base})
for
customer
in
client.v1.customers.
list
({
"limit"
:
100
}).
auto_paging_iter
():
(customer.id, customer.email)
Stripe's library calls four hosts, api.stripe.com and three others: base_addresses sends each of them to the app.
HubSpot
Python
import
hubspot api = hubspot.Client.
create
(access_token=
credential
(
"hubspot"
,
"app"
), host=
app
(
"hubspot"
)[
"base_url"
]) contacts = api.crm.contacts.
get_all
(properties=[
"email"
,
"firstname"
])
# every page
host takes the app's address as it is, with no trailing slash, in place of https://api.hubapi.com . Use the Service Key ( app ): a blank sandbox's HubSpot has no user: credential.
GitHub
GitHub's own clients are Octokit, for JavaScript (shown here), Ruby and .NET, and the gh command line. GitHub publishes no Python library; PyGithub and githubkit are community ones. The examples write to owner/support-bot , the repository the example in Apps and credentials makes: in a blank sandbox, run that one first.
const
{ Octokit } =
require
(
"octokit"
);
const
octokit =
new
Octokit
({ baseUrl:
app
(
"github"
).base_url, auth:
credential
(
"github"
) }); octokit.hook.
before
(
"request"
, (options) => { options.headers[
"x-github-api-version"
] =
"2022-11-28"
; });
await
octokit.rest.issues.
create
({ owner:
"owner"
, repo:
"support-bot"
, title:
"Checkout page times out"
});
const
issues =
await
octokit.
paginate
(octokit.rest.issues.listForRepo, { owner:
"owner"
, repo:
"support-bot"
, per_page:
100
});
const
{ viewer } =
await
octokit.
graphql
(
"{ viewer { login } }"
);
from
github
import
Auth, Github g =
Github
(base_url=
app
(
"github"
)[
"base_url"
], auth=Auth.
Token
(
credential
(
"github"
))) repo = g.
get_repo
(
"owner/support-bot"
) repo.
create_issue
(title=
"Checkout page times out"
)
for
issue
in
repo.
get_issues
(state=
"open"
):
# every page
(issue.number, issue.title)
from
githubkit
import
GitHub github =
GitHub
(
credential
(
"github"
), base_url=
app
(
"github"
)[
"base_url"
]) github.rest.issues.
create
(
"owner"
,
"support-bot"
, title=
"Checkout page times out"
)
for
issue
in
github.rest.
paginate
(github.rest.issues.list_for_repo, owner=
"owner"
, repo=
"support-bot"
):
(issue.number, issue.title)
Octokit takes the app's address with no trailing slash as baseUrl . With a slash it asks for //repos/… , and every call answers 404. Without an X-GitHub-Api-Version header, a few writes, issues.create among them, answer with a Deprecation header and Octokit prints a warning; the hook above sends the version. octokit 5 is an ES module: require loaded it on Node 25.8, and where require cannot load an ES module, load it with await import("octokit") inside the async function.
PyGithub and githubkit take the address as base_url , with or without a trailing slash. githubkit sends X-GitHub-Api-Version: 2026-03-10 , which the app serves.
Release uploads go to another host. Octokit's repos.uploadReleaseAsset sends the file to uploads.github.com unless you pass the release's upload_url as url ; without it, your agent would call the real GitHub with its token. githubkit's repos.upload_release_asset posts to the API's address, which answers 501: upload through a second client, GitHub(token, base_url=release.upload_url.split("/repos/")[0]) . PyGithub's upload_asset follows upload_url by itself.
gh
gh reaches the app as it reaches a GitHub Enterprise Server host: give it the address's host as GH_HOST and the token as GH_ENTERPRISE_TOKEN ( gh uses GH_TOKEN only for github.com and ghe.com). It then calls …/api/v3/ and …/api/graphql , which the app serves.
Shell
export
GH_HOST=
"${STATEWEAVE_GITHUB_URL#https://}"
GH_ENTERPRISE_TOKEN=
"$STATEWEAVE_GITHUB_USER_TOKEN"
GH_TELEMETRY=0 gh api user
--jq
.login gh issue create
-R
"$GH_HOST/owner/support-bot"
--title
"Checkout page times out"
--body
"Seen on mobile"
gh issue list
-R
"$GH_HOST/owner/support-bot"
GH_TELEMETRY=0 turns gh 's telemetry off. gh was tested through a local socket, so its paths and its token were checked, but not its TLS connection to a hosted run.
Other libraries
Any library works if it lets you set where it sends requests and which token it uses. Watch for two things:
A hard-coded host. Some libraries build the address from an account or shop name, like ShopifyAPI above. Find the setting that changes the domain; without one, the library can't reach StateWeave.
Its own sign-in. A run hands over access tokens, not client secrets or refresh tokens. Give the library the token directly instead of running its OAuth flow.
Tell us at support@stateweave.net if a library you use doesn't work.