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
semantic_search(query, *, agent_id?, limit?, threshold?) Search messages by meaning (vector similarity)
upload_attachment(message_id, *, filename, mime_type, size_bytes) Upload an attachment
get_attachment_url(attachment_id) Get a download URL for an attachment

Semantic search ranks messages by meaning, not keywords — results carry a similarity score (0-1):

results = client.messages.semantic_search("unpaid invoices from suppliers", limit=5)
for r in results:
    print(f"{r.similarity:.2f} {r.channel} {r.content[:60]}")

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.emails.drafts

Composed-but-not-sent emails owned by an agent. Drafts may be incomplete (no recipients, subject, or body yet); send atomically converts a draft into a delivered message and deletes the draft.

Method Description
create(*, agent_id, from_identity_id?, to?, cc?, bcc?, subject?, body?, body_html?, in_reply_to?, references?, metadata?) Create a draft (only agent_id required)
get(draft_id) Get a draft by ID
list(*, cursor?, limit?, agent_id?) List drafts with pagination
send(draft_id) Send the draft — returns the new MessageOutput
delete(draft_id) Discard a draft — returns its final state
draft = client.emails.drafts.create(
    agent_id=agent.id,
    to=["user@example.com"],
    subject="Quarterly report",
    body="Numbers attached below.",
)
message = client.emails.drafts.send(draft.id)  # draft is deleted server-side

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.voices

Browse the multilingual voice catalog (English, Spanish, French, German, Italian, Japanese, Dutch, and more). Each voice carries descriptive metadata and a vendor-neutral sample_url preview.

Method Description
list(*, language?, gender?) List catalog voices, optionally filtered by language or gender
# Only Spanish voices
result = client.voices.list(language="es")
for voice in result["voices"]:
    print(voice.id, voice.name, voice.language, voice.descriptors)
    if voice.sample_url:  # vendor-neutral preview served from the API host
        print("preview:", voice.sample_url)

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.7.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.7.0
File Size Uploaded Provenance Actions
anima_labs-0.7.0.tar.gz 77.5 kB With provenance Details for anima_labs-0.7.0.tar.gz

Built distribution (wheel)

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

Total release size: 145.9 kB

Release files / anima_labs-0.7.0.tar.gz

Download URL anima_labs-0.7.0.tar.gz
Size 77.5 kB
Tags Source
SHA-256 checksum
How to use checksums
6ac0873cabaede092c7310d32ff4645ba42cf97105d6e866e9ad31a057e76ac5
BLAKE2b-256 checksum
How to use checksums
899a747c8963919c1943b5330dd2b855c02f81c79c4db92d45bdac623802709d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

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 24, 2026.

Transparency log

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

Download URL anima_labs-0.7.0-py3-none-any.whl
Size 68.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
758df3bdf74756215dae1a2a9dd99a320c9b7fe5eaa6040ae96c6d9e95bccd47
BLAKE2b-256 checksum
How to use checksums
06b950f918dbba41f8b55a83e0819d2e7b6ba64cb22ad03c1b95a8b8c49c2824
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

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 24, 2026.

Transparency log

Security for anima-labs 0.7.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.7.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 24, 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