auditledge 0.1.1

Official Python SDK for Auditledge — Audit Log API for SaaS developers

auditledge-python

Official Python SDK for Auditledge — the audit log API for SaaS developers.

Add "who did what and when" to your app in minutes.

Install

pip install auditledge

Quickstart

from auditledge import AuditLedge

client = AuditLedge('your_api_key')

# Log an event
client.log({
    'actor': {'id': 'user_123', 'name': 'Alice', 'email': '[e-mail]'},
    'action': 'invoice.deleted',
    'resource': {'type': 'invoice', 'id': 'inv_456', 'name': 'Invoice #1042'},
    'organization_id': 'org_789',
    'metadata': {'ip': '192.168.1.1'}
})

# Query events
result = client.query({
    'organization_id': 'org_789',
    'limit': 50
})
print(result['events'])   # list of events
print(result['total'])    # total matching count

# Query with filters
result = client.query({
    'actor_id': 'user_123',
    'action': 'invoice',        # partial match
    'start_date': '2026-01-01T00:00:00Z',
    'end_date': '2026-12-31T23:59:59Z',
})

# Export as CSV
csv_data = client.export({'format': 'csv', 'organization_id': 'org_789'})

# Export as JSON
events = client.export({'format': 'json', 'organization_id': 'org_789'})

# Check quota usage
info = client.usage()
print(info['plan'])              # 'free', 'starter', or 'growth'
print(info['events_this_month']) # events logged this month
print(info['events_limit'])      # monthly cap

Django / FastAPI Example

from auditledge import AuditLedge

audit = AuditLedge('your_api_key')

def delete_invoice(request, invoice_id):
    invoice = Invoice.objects.get(id=invoice_id)
    invoice.delete()

    audit.log({
        'actor': {'id': str(request.user.id), 'name': request.user.get_full_name()},
        'action': 'invoice.deleted',
        'resource': {'type': 'invoice', 'id': str(invoice_id)},
        'organization_id': str(request.user.organization_id),
        'metadata': {'ip': request.META.get('REMOTE_ADDR')}
    })

Reference

AuditLedge(api_key, base_url=None, timeout=30)

Param	Description
api_key	Your Auditledge API key
base_url	Override the API base URL (optional)
timeout	HTTP request timeout in seconds (default 30)

log(event) → dict

Log an audit event. All fields marked required will raise AuditLedgeError locally before the request is made.

Field	Required	Description
actor.id	Yes	ID of the user or service performing the action
actor.name	No	Display name
actor.email	No	Email address
action	Yes	Dot-notation string, e.g. invoice.deleted
resource.type	Yes	Resource type, e.g. invoice
resource.id	Yes	Resource ID
resource.name	No	Display name
organization_id	No	Defaults to the key's organisation
metadata	No	Any additional key/value data
timestamp	No	ISO 8601 string — defaults to now

query(filters) → dict

Filter	Description
organization_id	Filter by organisation
actor_id	Exact match on actor ID
actor_name	Partial match on actor name
action	Partial match on action string
resource_type	Exact match on resource type
search	Full-text search across action, actor name, and resource type
start_date	ISO 8601 — events on or after this date
end_date	ISO 8601 — events on or before this date
limit	Max results (default 20)
offset	Pagination offset (default 0)

Returns { events: [...], total: int, limit: int, offset: int }.

get(event_id) → dict

Fetch a single event by ID.

export(options) → str or list

Option	Description
format	'csv' or 'json' (default 'json')
organization_id	Filter by organisation
start_date	ISO 8601 start date
end_date	ISO 8601 end date

Returns a str for CSV, or a list of event dicts for JSON.

usage() → dict

Returns { plan, events_this_month, events_limit, retention_days }.

Links

• 🌐 Website: auditledge.com
• 📖 Docs: docs.auditledge.com
• 🐛 Issues: github.com/auditledge/auditledge-python/issues

License

MIT