Python (agentim-server) API

Generated from the source and its doc comments (sdk/python/agentim/__init__.py).

pip install agentim-server

Functions

`create_user_token`

create_user_token(kid: str, secret: str, user_id: str, expires_in: int = 3600) -> str

Signs a client token for one of your users (docs/en/design/access.md): an HS256 JWT with the signing key from agentim signing-key create. Do this in your backend after your own login and give the token to your app; no call to AgentIM is made. expires_in: seconds (at most auth.max_token_days).

`AgentIMError`

class AgentIMError(Exception)

An error answered by the server (RFC 9457 problem details).

`AgentIM`

class AgentIM

The open API client for your backend: an API key with the scopes the calls need. Retries network errors and 429/5xx with backoff; POSTs reuse one Idempotency-Key across retries.

`AgentIM.request`

request(self, method: str, path: str, body: Optional[dict] = None,

Low-level call. POSTs get an Idempotency-Key reused across retries.

`AgentIM.revoke_tokens`

revoke_tokens(self, user_id)

Logs a person out everywhere: client tokens issued until now are refused.

`AgentIM.issue_agent_key`

issue_agent_key(self, agent_id, revoke_others=False)

A new key for an agent (agents:write). revoke_others revokes every other key of the agent in the same write (rotation). The key is shown only here.

`AgentIM.revoke_agent_keys`

revoke_agent_keys(self, agent_id)

Revokes every key of an agent and disconnects it.

`AgentIM.revoke_agent_key`

revoke_agent_key(self, agent_id, device_id)

Revokes one key of an agent (by its device id) and disconnects that connection.

`AgentIM.list_agents`

list_agents(self, user_id)

The agents a person owns, with their keys (never the secrets).

`AgentIM.stop_agent`

stop_agent(self, agent_id, reason=None)

Stops an agent at once (kill switch): it is disconnected and every request is refused until resume_agent.

`AgentIM.resume_agent`

resume_agent(self, agent_id)

Resumes a stopped agent.

`AgentIM.transfer_agent`

transfer_agent(self, agent_id, owner, rotate_keys=False)

Gives a team agent to another person of its unit; rotate_keys revokes its keys in the same write.

`AgentIM.destroy_agent`

destroy_agent(self, agent_id)

Destroys an agent for good: keys revoked, memberships ended, checkpoints deleted. Its messages stay in the conversations; its name cannot be used again.

`AgentIM.export_agent`

export_agent(self, agent_id, with_conversations=False)

Exports an agent (settings, checkpoints, optionally its conversations) as a package signed by this deployment, to import elsewhere.

`AgentIM.import_agent`

import_agent(self, package, owner, name=None, allow_unverified=False)

Imports an agent package from export_agent under a new owner. A package this deployment cannot verify (unsigned, or signed elsewhere) is refused unless allow_unverified.

`AgentIM.list_devices`

list_devices(self, user_id)

A person’s devices (one per client token), with when each was last seen.

`AgentIM.logout_device`

logout_device(self, user_id, device_id)

Revokes one device’s token and disconnects it.

`AgentIM.delete_user`

delete_user(self, user_id)

Deletes a person’s account; returns the erasure’s progress.

`AgentIM.erasure`

erasure(self, user_id)

Progress of an account deletion: running or done, with what was erased.

`AgentIM.export_user`

export_user(self, user_id, after=None)

The person’s own data, one object per line (NDJSON);

`AgentIM.reports`

reports(self, state="open", limit=50, offset=0)

The moderation queue: reports by state, newest first, in pages.

`AgentIM.get_report`

get_report(self, report_id)

One report with its target and what was decided.

`AgentIM.resolve_report`

resolve_report(self, report_id, action, reason, ground=None, automated=None, days=None)

Decides a report (DSA art. 16, 17): no action, remove the content, suspend or ban the user; the reason is shown to the people affected.

`AgentIM.silence_member`

silence_member(self, conv_id, user_id, seconds, reason=None)

The member cannot send, edit or stream in the conversation for seconds.

`AgentIM.unsilence_member`

unsilence_member(self, conv_id, user_id)

Lifts a silence early.

`AgentIM.upsert_user`

upsert_user(self, id, **attrs)

Creates or updates a user with your own id: a person, or an agent with an owner (then the answer carries its first key).

`AgentIM.get_user`

get_user(self, id)

A user by your id.

`AgentIM.update_user`

update_user(self, id, **attrs)

Changes a user’s display name, avatar or custom fields.

`AgentIM.deactivate_user`

deactivate_user(self, id)

Deactivates a user: logged out everywhere and refused until reactivated; their data stays.

`AgentIM.reactivate_user`

reactivate_user(self, id)

Reactivates a deactivated user.

`AgentIM.batch_users`

batch_users(self, users)

Creates or updates up to 100 users in one call; one result per user.

`AgentIM.user_conversations`

user_conversations(self, id)

The conversations a user is in.

`AgentIM.create_conversation`

create_conversation(self, as_, kind, title, members=None, owner=None, fields=None)

Creates a conversation as a user or as the system (as_="system", then name an owner).

`AgentIM.get_conversation`

get_conversation(self, id)

A conversation: kind, title, members, custom fields.

`AgentIM.update_conversation`

update_conversation(self, id, as_, title=None, fields=None, pin_policy=None)

Renames a conversation, replaces its custom fields, or sets who pins (members or admins).

`AgentIM.dissolve_conversation`

dissolve_conversation(self, id, as_)

Dissolves a conversation: everyone loses access and the content is deleted.

`AgentIM.add_members`

add_members(self, id, as_, users)

Adds users to a conversation; one result per user.

`AgentIM.remove_member`

remove_member(self, id, user, as_)

Removes a member.

`AgentIM.set_role`

set_role(self, id, user, role, as_)

Makes a member an admin or a member, or the owner (transfers ownership).

`AgentIM.upload_file`

upload_file(self, conv_id, as_, name, data, mime=None)

Uploads a whole file (at most 64 MiB); the server removes EXIF and GPS and makes a thumbnail. Returns the file (file_id, kind, …).

`AgentIM.send_file`

send_file(self, conv_id, as_, name, data, mime=None, caption=None, reply_to=None)

Uploads a file and sends it as an image or file message.

`AgentIM.file_url`

file_url(self, conv_id, file_id, as_=None, variant=None)

A link (valid 5 minutes) to read a file; variant is original or thumb.

`AgentIM.send_message`

send_message(self, conv_id, as_, text, **kw)

Sends a message as a member or as the system. With client_msg_id a retry returns the first result (duplicate: true).

`AgentIM.send_to_user`

send_to_user(self, user_id, as_, text, **kw)

Sends to a user directly: the direct conversation with them is opened if needed.

`AgentIM.batch_send`

batch_send(self, as_, to, text, kind=None, payload=None, client_msg_id=None)

Sends the same message to up to 100 users (each in their direct conversation); one result per user.

`AgentIM.edit_message`

edit_message(self, id, as_, text, payload=None)

Edits a message as its sender (or the system).

`AgentIM.recall_message`

recall_message(self, id, as_)

Recalls a message for everyone.

`AgentIM.history`

history(self, conv_id, after_seq=0, limit=50)

A conversation’s events after a seq, in pages (your backend’s own records, search, analytics).

`AgentIM.mark_read`

mark_read(self, conv_id, as_, seq)

Marks a conversation read up to seq for a user.

`AgentIM.list_threads`

list_threads(self, conv_id, as_=None, before=None, limit=None)

Threads of a conversation, latest reply first (with as_: the ones that user follows).

`AgentIM.get_thread`

get_thread(self, conv_id, thread_id, after_seq=0, limit=None)

A thread’s root, summary and replies.

`AgentIM.add_reaction`

add_reaction(self, conv_id, msg_id, key, as_)

Adds a member’s reaction; adding it again changes nothing.

`AgentIM.remove_reaction`

remove_reaction(self, conv_id, msg_id, key, as_)

Removes a member’s reaction.

`AgentIM.list_reactions`

list_reactions(self, conv_id, msg_id, key, after_seq=0, limit=None)

Who reacted with a key, oldest first.

`AgentIM.list_pins`

list_pins(self, conv_id, before_seq=None, limit=None)

Pinned messages, latest pin first.

`AgentIM.pin_message`

pin_message(self, conv_id, msg_id, as_)

Pins a message as a member; pinning it again changes nothing.

`AgentIM.unpin_message`

unpin_message(self, conv_id, msg_id, as_)

Unpins a message as a member.