Overview
The Shares API enables you to share alerts with other users and manage access permissions. Each share can have different permission levels (read, write, admin) to control what actions users can perform.
Methods
Get Shares
Fetch all shares for an alert.
client.get_shares(
account_id: str,
alert_id: str
) -> SharesResponse
SharesResponse containing list of shares
Example:
from mention import MentionClient
client = MentionClient(access_token="your-token")
shares_response = client.get_shares("acc_123456", "alert_123")
for share in shares_response.shares:
print(f"Shared with: {share.email}")
print(f"Permission: {share.permission}")
{
"shares": [
{
"id": "share_789",
"alert_id": "alert_123",
"user_id": "user_456",
"email": "[email protected]",
"permission": "write",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:00:00Z"
},
{
"id": "share_790",
"alert_id": "alert_123",
"user_id": null,
"email": "[email protected]",
"permission": "read",
"created_at": "2024-01-18T14:30:00Z",
"updated_at": "2024-01-18T14:30:00Z"
}
]
}
Get Share
Fetch a single share by ID.
client.get_share(
account_id: str,
alert_id: str,
share_id: str
) -> Share
Share object
Example:
share = client.get_share(
"acc_123456",
"alert_123",
"share_789"
)
print(f"Share with: {share.email}")
print(f"Permission: {share.permission}")
print(f"Created: {share.created_at}")
Create Share
Share an alert with another user.
from mention import CreateShareRequest, SharePermission
client.create_share(
account_id: str,
alert_id: str,
request: CreateShareRequest
) -> Share
request
CreateShareRequest
required
Share creation request
Email address of the user to share with
request.permission
SharePermission
default:"read"
Permission level (read, write, admin)
Share object
Example:
from mention import MentionClient, CreateShareRequest, SharePermission
client = MentionClient(access_token="your-token")
# Share with write permission
request = CreateShareRequest(
email="[email protected]",
permission=SharePermission.WRITE
)
share = client.create_share("acc_123456", "alert_123", request)
print(f"Alert shared with: {share.email}")
print(f"Permission level: {share.permission}")
{
"id": "share_791",
"alert_id": "alert_123",
"user_id": "user_789",
"email": "[email protected]",
"permission": "write",
"created_at": "2024-01-20T15:00:00Z",
"updated_at": "2024-01-20T15:00:00Z"
}
Update Share
Update the permission level of an existing share.
from mention import UpdateShareRequest, SharePermission
client.update_share(
account_id: str,
alert_id: str,
share_id: str,
request: UpdateShareRequest
) -> Share
request
UpdateShareRequest
required
Share update request
Share object
Example:
from mention import UpdateShareRequest, SharePermission
# Upgrade permission to admin
request = UpdateShareRequest(
permission=SharePermission.ADMIN
)
share = client.update_share(
"acc_123456",
"alert_123",
"share_789",
request
)
print(f"Updated permission to: {share.permission}")
Delete Share
Revoke access by deleting a share.
client.delete_share(
account_id: str,
alert_id: str,
share_id: str
) -> bool
True if deletion was successful
Example:
success = client.delete_share(
"acc_123456",
"alert_123",
"share_789"
)
if success:
print("Share revoked successfully")
Permission Levels
The Shares API supports three permission levels:
Read
SharePermission.READ
- View mentions and alert data
- Cannot modify settings or curate mentions
- Cannot create tasks or tags
Use case: External partners, clients, or team members who need view-only access.
Write
SharePermission.WRITE
- All read permissions
- Curate mentions (mark as read, favorite, trash)
- Create and manage tasks
- Apply existing tags
Use case: Team members who actively monitor and respond to mentions.
Admin
SharePermission.ADMIN
- All write permissions
- Modify alert settings
- Create/delete tags
- Manage shares (add/remove users)
Use case: Team leads or managers who need full control over the alert.
Models
Share
Represents a share of an alert with another user.
| Field | Type | Description |
|---|
id | string | Share ID |
alert_id | string | Associated alert ID |
user_id | string | User ID (if user exists) |
email | string | Email address shared with |
permission | SharePermission | Permission level |
created_at | datetime | Creation timestamp |
updated_at | datetime | Last update timestamp |
SharePermission
Permission level enumeration:
READ: Read-only accessWRITE: Read and curate accessADMIN: Full administrative access
CreateShareRequest
Request for creating a new share.
| Field | Type | Required | Default | Description |
|---|
email | string | Yes | - | Email to share with |
permission | SharePermission | No | read | Permission level |
UpdateShareRequest
Request for updating an existing share.
| Field | Type | Description |
|---|
permission | SharePermission | New permission level |