Puras SDK Client Reference

puras.Client is the external half of the SDK: call skills you've deployed from your own backend, script, or CI. It's the counterpart to the in-skill runtime — instead of running inside a job, it submits jobs and hands back the result. Both ship in the same pip install puras.

Authenticate with a workspace API key (puras_live_…): pass api_key= or set the PURAS_API_KEY environment variable. Mint a key from the dashboard.

import puras

client = puras.Client(skillpack="<skillpack-id>")   # PURAS_API_KEY from env
out = client.run("ugc-ad", {"product": url, "duration": 15})

Client

Call deployed skills.

Pass a fully-qualified workspace/skillpack/skill path to run/submit (copyable from a skill's page), or set a default skillpack once — a slug or UUID — and call skills by bare name.

Client(api_key: 'str | None' = None, skillpack: 'str | None' = None, *, api_base: 'str | None' = None, timeout: 'float' = 120.0)

Client.feedback(job_id: 'str', *, rating: 'int' = 0, comment: 'str | None' = None, end_user_id: 'str | None' = None) -> 'dict'

Record end-user feedback on a job's result.

rating is a thumb: +1 (good), -1 (bad), or 0 (comment-only). comment is free-form text (the user's words on why). At least one of a non-zero rating or a comment is required.

end_user_id keys the feedback to one of your end users (any opaque id of yours). Posting again with the same (job, end_user_id) overwrites that user's rating/comment in place, so a thumb can be toggled or a comment edited. Omit it and the feedback is keyed to the API key's identity instead (one row per job).

Returns the stored feedback object. Typical flow is run() → show the result → feedback(job_id, rating=+1).

Client.get(job_id: 'str') -> 'dict'

Fetch a job by id.

Client.run(skill: 'str', inputs: 'dict | None' = None, *, skillpack: 'str | None' = None, version: 'int | None' = None, timeout: 'float' = 600, poll_interval: 'float' = 2.0) -> 'dict'

Submit + wait, returning the skill's result. Raises JobError if it didn't succeed (including still-running when timeout elapses).

Waiting is client-side polling (poll_interval seconds between checks), so multi-minute media jobs work; timeout defaults to 10 minutes.

skill may be a "workspace/skillpack/skill" path (copyable from the skill's page) or a bare name resolved against the default skillpack.

Pass version=N to pin the run to a specific deployment version of the skillpack; omit it to use the active deployment.

Client.submit(skill: 'str', inputs: 'dict | None' = None, *, skillpack: 'str | None' = None, version: 'int | None' = None, wait: 'bool' = False, timeout: 'int' = 60) -> 'dict'

Submit a job. wait=True blocks server-side up to timeout seconds (the API caps the server-side wait at 60 — short jobs only; for longer runs use run() or wait(), which poll client-side). Returns the job object ({id, status, result, error, …}).

skill may be a fully-qualified path — "workspace/skillpack/skill" (copyable from the skill's page) or "skillpack/skill" for one of your own — in which case the skillpack is taken from the path. A bare skill name uses the default skillpack passed here or to Client(...).

version pins the run to a specific deployment version of the skillpack (e.g. version=3); omit it to use the active deployment, which follows new deploys. Pinning lets you keep running a release you've validated even after newer versions are deployed.

Client.wait(job_id: 'str', *, timeout: 'float' = 600, poll_interval: 'float' = 2.0) -> 'dict'

Poll a job until it reaches a terminal status (succeeded / failed / cancelled) or timeout seconds elapse. Returns the last job object — check status; a job still running at timeout is returned as-is.

Exceptions

PurasAPIError

Non-2xx response from the Puras API.

JobError

A job finished in a non-succeeded state (failed/cancelled/timeout).