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

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.6.1
File Size Uploaded Provenance Actions
anima_labs-0.6.1.tar.gz 76.1 kB With provenance Details for anima_labs-0.6.1.tar.gz

Built distribution (wheel)

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

Total release size: 144.2 kB

Release files / anima_labs-0.6.1.tar.gz

Download URL anima_labs-0.6.1.tar.gz
Size 76.1 kB
Tags Source
SHA-256 checksum
How to use checksums
652a20f3bbeea8e4319fdfb87b4993da7fe0c189deecbff26b0ca16e825fc64b
BLAKE2b-256 checksum
How to use checksums
68ce6acb944adb1cf9c91ab344182f30338d4c461c290c3a45cd6d25014be460
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 17, 2026.

Transparency log

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

Download URL anima_labs-0.6.1-py3-none-any.whl
Size 68.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0ab93afa556ad5566a67729a715035775742cbc74011e83a6faa59e024aba206
BLAKE2b-256 checksum
How to use checksums
fbb9dab37ded11d441f0b8ae422dc94259596e41d93d339402d1d3148d3062b8
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 17, 2026.

Transparency log

Security for anima-labs 0.6.1

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.6.1.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 17, 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