Behavior & edge cases

​

Retries and rate limits

patient_client = PersonaClient(
    "https://api.persona.hasanraiyan.me",
    credential=os.environ["PERSONA_CREDENTIAL"],
    max_retries=5,  # retry up to 5 times on 429 before raising
)

​

Pagination

result = persona.agents.list({"page": 2, "limit": 20})
items = result["items"]
pagination = result["pagination"]   # {"total", "page", "limit", "pages"}

• Defaults: page=1, limit=20 (per endpoint; passed explicitly to override).
• pagination["total"] is the total matching count across all pages — use it, not len(items).
• pagination["pages"] is ceil(total / limit) — check it to know whether there’s more, rather than inferring from len(items) vs. limit.
• providers.list() is the one exception: a plain bare list, no params at all — Providers have no discovery concept, so there’s nothing to page or filter by.
• search (where offered) is free-text against name/description (plus tagline on Agents), and scope: "mine" restricts to the asserted external user’s own items (runtime context only — ignored or empty on a control-plane client).

​

Idempotency keys

skill = persona.skills.create(
    {"name": "Resume Reviewer", "description": "...", "instructions": "..."},
    idempotency_key=str(uuid.uuid4()),  # generate once per logical create
)

​

_id vs id

​

Populated vs. bare fields

​

Empty results and existence-hiding

• providers.list() on a runtime-plane client returns [] — a Provider’s ownership can only ever be "PersonaUser" or "Project", never "ExternalUser", so a client with external_user_id set can never own any. Same for audit_logs.list(). Silent empty result, not an error.
• get()/update()/delete() never distinguish “not found” from “not authorized” — a caller that can’t own a resource gets the same 404 NOT_FOUND as a caller asking for a nonexistent id. Don’t build error-driven existence probes.
• ProviderTestConnectionResult["success"] == False is a result, not a thrown error — the call reached the endpoint but the credentials/URL were rejected.
• KnowledgeSearchResult["score"] can be None if the vector store didn’t return a similarity score.
• ResourceUsage["agents"] is a preview capped at 20 — agentCount is the real total.
• AuditLogEntry["actorIdentity"]/["targetResourceId"] are None when not applicable.

​

Bulk delete

result = persona.skills.bulk_delete(["id1", "id2"])
print(result["deleted"])  # ids that succeeded
print(result["failed"])   # [{"id": ..., "reason": ...}] for anything that didn't

​

Ordering

• threads.list() returns Threads most recently active first — the only ordering guarantee in the SDK. Everything else has no documented ordering contract; don’t rely on the order of list() items beyond the search relevance of search.

​

Timeouts and cancellation

​

HTTP client lifecycle

• The SDK creates its own httpx.Client/httpx.AsyncClient if you don’t pass http_client=, and closes it when you close()/use the context manager.
• If you pass http_client=, the SDK never closes it (not even via close()/context-manager exit) — ownership stays with you. This makes sharing one httpx client across many per-request PersonaClient instances safe.
• Non-JSON success responses (file downloads) return the raw httpx.Response — read .content/.text/.iter_bytes()/.aiter_bytes() yourself. Non-JSON failure responses raise PersonaApiError with code == "NON_JSON_ERROR_RESPONSE".

​

Validation and envelope behavior

• Envelope decoding: a response body with success: False raises even on a 2xx status; a data key is unwrapped (json_body["data"]) so methods return the payload directly, not the envelope.
• /whoami and similar endpoints that omit the fuller envelope are returned as-is.
• Request bodies are serialized as JSON with camelCase field names matching the API (providerId, systemPrompt, …) even though method parameters are snake_case.
• Multipart uploads (files.upload(), knowledge.upload_documents()) set their own Content-Type with a boundary — never force application/json on them.
• Query params with None values are omitted (build_url filters them out).