Skip to main content
cpsl.Client is the lightweight Python client for talking to deployed Capsule apps from outside the app runtime. You will usually reach for it when the app already exists and you want to talk to it from somewhere else, such as a smoke test, admin script, or another Python service. It is useful for:
  • deploy smoke tests
  • scripts and admin tools
  • cron jobs
  • other Python services that want to call a Capsule app

​
Worked example

The most common use is a deploy smoke test for a real app: 
import cpsl

client = cpsl.Client()

first = client.chat(
    "support-ops",
    "How many threads are waiting for review right now?",
)
second = client.chat(
    "support-ops",
    "Turn that into a two-step triage plan.",
    session_id=first.session_id,
)

assert first.text.strip()
assert second.text.strip()
assert first.session_id == second.session_id
That pattern is useful because it exercises both the app’s answer quality and its session continuity after a deploy.

​
Setup

The client authenticates from capsule login by default: 
import cpsl

client = cpsl.Client()
You can also pass credentials manually: 
client = cpsl.Client(token="...", gateway_url="https://gateway.capsule.new")
If you have already run capsule login, the zero-argument form is usually all you need.

​
App lookup methods

MethodPurpose
list_apps()List apps in the workspace
get_app(name_or_id)Get metadata for one app
create_checkout(app, return_url="")Create a checkout URL
list_payments(app)List payments for an app
get_earnings(app)Get earnings summary

​
Chat methods

​
chat(app, text, session_id=None)

Send a message and wait for the full response. 
reply = client.chat("support-ops", "How many support threads are waiting for review right now?")
print(reply.text)
If you are writing a quick post-deploy smoke test, this is usually the most convenient entry point. Returns ChatResponse with:
  • text
  • session_id
  • request_id
  • raw

​
stream(app, text, session_id=None)

Stream a response via SSE: 
for chunk in client.stream("support-ops", "Summarize the riskiest support threads."):
    print(chunk.text, end="")
This is handy when you want your script to show progress instead of waiting for the entire response. Each StreamChunk exposes:
  • event
  • data
  • text convenience property
  • done convenience property

​
Session continuity

Pass session_id if you want multiple client calls to continue the same conversation: 
first = client.chat(
    "support-ops",
    "How many threads are waiting for review, and which queue looks busiest?",
)
second = client.chat(
    "support-ops",
    "Turn that into a two-step triage plan.",
    session_id=first.session_id,
)
Without session_id, each call starts a fresh conversation.

​
Typical use

Example smoke test: 
import cpsl

client = cpsl.Client()
reply = client.chat("support-ops", "Give me a one-sentence triage plan for the current support queue.")

assert reply.text.strip()
assert reply.session_id
print("smoke test passed")

​
See also