Skip to main content

Anima Python SDK

PyPI version Python versions License: MIT

The official Python SDK for the Anima API -- unified agent identity infrastructure for email, phone, and vault.

Installation

pip install anima-labs

Quick start

from anima import Anima

client = Anima(api_key="sk-...")

# Create an agent
agent = client.agents.create(
    org_id="org_123",
    name="Support Bot",
    slug="support-bot",
)

# Send an email
message = client.messages.send_email(
    agent_id=agent.id,
    to=["user@example.com"],
    subject="Hello from Anima",
    body="Your order has been shipped!",
)

print(message.id)
client.close()

Async usage

Every method is available in an async variant via AsyncAnima:

import asyncio
from anima import AsyncAnima

async def main():
    async with AsyncAnima(api_key="sk-...") as client:
        agents = await client.agents.list(org_id="org_123")
        for agent in agents.items:
            print(agent.name)

asyncio.run(main())

Resources

Both Anima (sync) and AsyncAnima have identical resource interfaces. All async methods use await.

client.agents

Method Description
create(*, org_id, name, slug, email?, provision_phone?, metadata?) Create a new agent
get(agent_id) Get an agent by ID
list(*, cursor?, limit?, org_id?, status?, query?) List agents with pagination
update(agent_id, *, name?, slug?, status?, metadata?) Update agent fields
delete(agent_id) Delete an agent
rotate_key(agent_id) Rotate an agent's API key

client.messages

Method Description
send_email(*, agent_id, to, subject, body, cc?, bcc?, body_html?, attachments?, in_reply_to?, references?, headers?, metadata?) Send an email (attachments + threading supported)
send_sms(*, agent_id, to, body, media_urls?, metadata?) Send an SMS
get(message_id) Get a message by ID
list(*, cursor?, limit?, agent_id?, thread_id?, channel?, direction?, date_from?, date_to?) List messages with filters
search(query, *, agent_id?, channel?, direction?, status?, date_from?, date_to?, cursor?, limit?) Full-text search messages
upload_attachment(message_id, *, filename, mime_type, size_bytes) Upload an attachment
get_attachment_url(attachment_id) Get a download URL for an attachment

Sending with an attachment (dict in the API wire shape — exactly one of content (base64) or url):

message = client.messages.send_email(
    agent_id=agent.id,
    to=["user@example.com"],
    subject="Your invoice",
    body="Invoice attached.",
    attachments=[
        {"filename": "invoice.pdf", "contentType": "application/pdf", "content": pdf_base64},
    ],
)

client.inboxes

Method Description
create(*, username?, domain?, display_name?, agent_id?) Create an inbox (address generated when omitted)
get(inbox_id) Get an inbox by ID
list(*, cursor?, limit?, query?) List inboxes with pagination
update(inbox_id, *, display_name?, agent_id?) Update inbox fields
delete(inbox_id) Delete an inbox

client.emails

Method Description
list(*, cursor?, limit?, agent_id?) List emails with pagination
upload_attachment(message_id, *, filename, mime_type, size_bytes) Upload an email attachment
get_attachment_url(attachment_id) Get a download URL for an attachment

client.phones

Method Description
provision(*, agent_id, country_code?, area_code?, capabilities?) Provision a phone number
get(phone_id) Get phone details
list(*, cursor?, limit?, agent_id?) List phone numbers
release(phone_id) Release a phone number
update_config(phone_id, *, is_primary?, ten_dlc_status?, metadata?) Update phone configuration

client.domains

Method Description
add(*, domain) Add a custom domain
get(domain_id) Get domain details
list() List all domains
delete(domain_id) Remove a domain
update(domain_id, *, feedback_enabled?) Update domain settings
verify(domain_id) Trigger domain verification
dns_records(domain_id) Get required DNS records
deliverability(domain_id) Get deliverability statistics
zone_file(domain_id) Export the domain zone file

client.vault

Method Description
provision(*, agent_id) Provision a vault for an agent
deprovision(*, agent_id) Deprovision an agent's vault
list_credentials(*, agent_id, type?) List stored credentials
get_credential(credential_id) Get a credential by ID
create_credential(*, agent_id, type, name, notes?, login?, card?, identity?, fields?, favorite?, generate_password?) Store a new credential. generate_password={...} has the vault mint the login password server-side — stored, never returned (masked ref only)
update_credential(credential_id, *, name?, notes?, login?, card?, identity?, fields?, favorite?) Update a credential
delete_credential(credential_id) Delete a credential
search(*, agent_id, search, type?) Search credentials
generate_password(*, length?, uppercase?, lowercase?, numbers?, symbols?) Generate a secure password
get_totp(credential_id) Get a TOTP code
status(agent_id) Get vault status
sync(agent_id) Force vault sync

client.extension

Method Description
connect(*, agent_id?, ttl?) Mint a one-time connect handoff for a headless browser-extension worker. With a master key pass agent_id; with an agent key omit it. ttl is "15m", "1h", or "session". Returns a connect_url (no secret).
handoff = client.extension.connect(agent_id="agent_123", ttl="15m")
print(handoff.connect_url)  # open in the extension worker to complete the handshake

client.security

Method Description
scan_content(*, org_id, channel, body, agent_id?, subject?, metadata?) Scan content for threats
list_events(*, org_id, agent_id?, type?, severity?, cursor?, limit?) List security events

client.organizations

Method Description
create(*, name, slug, clerk_org_id?, tier?, settings?) Create an organization
get(org_id) Get organization details
list(*, cursor?, limit?, query?) List organizations
update(org_id, *, name?, slug?, clerk_org_id?, tier?, settings?) Update an organization
delete(org_id) Delete an organization
rotate_key(org_id) Rotate the master API key

client.webhooks

Method Description
create(*, url, events, description?, active?, auth_config?, rate_limit_per_minute?, max_attempts?) Register a webhook endpoint
get(webhook_id) Get webhook details
list(*, cursor?, limit?) List webhooks
update(webhook_id, *, url?, events?, description?, active?, auth_config?, rate_limit_per_minute?, max_attempts?) Update a webhook
delete(webhook_id) Delete a webhook
test(webhook_id, *, event?) Send a test event
list_deliveries(webhook_id, *, cursor?, limit?) List delivery attempts

Configure the auth Anima presents to your endpoint on each delivery (in addition to the always-on X-Anima-Signature HMAC) plus delivery throttling:

from anima import WebhookAuthBearer

webhook = client.webhooks.create(
    url="https://example.com/anima/webhook",
    events=["message.received"],
    # Also: WebhookAuthBasic(username=, password=),
    #       WebhookAuthCustomHeader(header_name=, value=), WebhookAuthNone().
    auth_config=WebhookAuthBearer(token="your-endpoint-token"),
    rate_limit_per_minute=120,  # omit for unlimited
    max_attempts=5,             # 1-10, default 3
)
print(webhook.id, webhook.auth_type)  # -> "wh_..." "BEARER"

The credential you set (token / password / header value) is write-only — it is never returned by get or list. To remove auth on update, pass WebhookAuthNone().

Webhook verification

Verify incoming webhook signatures to ensure authenticity:

from anima import Anima, AnimaError

payload = request.body          # raw request body (str or bytes)
sig = request.headers["anima-signature"]
secret = "whsec_..."

# Option 1: verify only
is_valid = Anima.verify_webhook_signature(payload, sig, secret)

# Option 2: verify and parse in one step
try:
    event = Anima.construct_webhook_event(payload, sig, secret)
    print(event.type, event.data)
except AnimaError:
    print("Invalid signature")

Error handling

All API errors raise typed exceptions that subclass AnimaError:

from anima import Anima, AuthenticationError, NotFoundError, RateLimitError, APIError

client = Anima(api_key="sk-...")

try:
    agent = client.agents.get("nonexistent")
except AuthenticationError:
    print("Invalid API key")
except NotFoundError:
    print("Agent not found")
except RateLimitError:
    print("Rate limited -- back off and retry")
except APIError as e:
    print(f"API error {e.status_code}: {e.message}")

Configuration

Parameter Default Description
api_key required Your Anima API key (sk-...)
base_url https://api.useanima.sh API base URL
timeout 30.0 Request timeout in seconds
max_retries 3 Max automatic retries on transient errors
client = Anima(
    api_key="sk-...",
    base_url="https://api.useanima.sh",  # custom endpoint
    timeout=60.0,
    max_retries=5,
)

Requirements

Documentation

Full API documentation is available at docs.useanima.sh.

Community

Join the Anima Discord to ask questions in #python-sdk, share what you're building in #showcase, and stay up to date with releases in #announcements.

License

This project is licensed under the MIT License. See LICENSE for details.

Metadata

Release files for anima-labs 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for anima-labs 0.5.0
File Size Uploaded Provenance Actions
anima_labs-0.5.0.tar.gz 63.7 kB With provenance Details for anima_labs-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for anima-labs 0.5.0
File Interpreter ABI Platform Actions
anima_labs-0.5.0-py3-none-any.whl Python 3 none any Details for anima_labs-0.5.0-py3-none-any.whl

Total release size: 127.1 kB

Release files / anima_labs-0.5.0.tar.gz

Download URL anima_labs-0.5.0.tar.gz
Size 63.7 kB
Tags Source
SHA-256 checksum
How to use checksums
996f73984fe5dce280c7482eb5ae18278653e9791d32fb33bb74e682fcadc038
BLAKE2b-256 checksum
How to use checksums
03a5aa5ca800083d748dc239357c3a6911748d6107992b56dc4bd508b1ec2de1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 16, 2026.

Transparency log

Release files / anima_labs-0.5.0-py3-none-any.whl

Download URL anima_labs-0.5.0-py3-none-any.whl
Size 63.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6757f56b397e7bedfcc7f0c3a7848f009d241f78aae800c2d8e605f70b0d6012
BLAKE2b-256 checksum
How to use checksums
f8a42b9dcf372dea9a02573ed837052d65e0810138a42cffdad94e6ab23e8ceb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 16, 2026.

Transparency log

Security for anima-labs 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for anima_labs-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page