Operations

Overview

This guide covers the operations available through the Insion SDK, including moderating and ingesting records, managing users, retrieving stored resources, pagination, and appeals.

All methods are available on InsionClient and AsyncInsionClient; await calls made through the async client. Required arguments are keyword-only unless shown as positional.

Shared models

Record

Argument	Required	Purpose
`client_id`	Yes	Your stable record identifier.
`name`	Yes	A human-readable record title.
`entity`	Yes	The record kind, such as `post` or `comment`.
`content`	Yes	Text, or `ContentExternalUrls` with text, image URLs, and external URLs.
`client_url`	No	A link to the record in your application.
`metadata`	No	Serializable application context.
`user`	No	An associated `UserInput`.
`passthrough`	Moderation only	Moderate without retaining record or user content.

User

Argument	Required	Purpose
`client_id`	Yes	Your stable identifier for the user.
`client_url`	No	A link to the user in your application.
`stripe_account_id`	No	The user's connected Stripe account ID.
`email`	No	The user's email address.
`name`	No	The user's display name.
`username`	No	The user's handle in your application.
`protected`	No	Prevent automated moderation actions from affecting them.
`metadata`	No	Serializable application context stored with the user.

Identifiers and pagination

Client IDs and Insion IDs

A client ID is supplied by your application, while an Insion ID is generated by Insion.

Value	Source	Used for
`client_id`	Your application	Ingesting, moderating, and deleting.
`record_id`	Returned by Insion	Retrieving a record.
`user_id`	Returned by Insion	Retrieving users and creating appeals.
`starting_after` / `ending_before`	Returned by Insion	Moving through list results.

Use only one cursor direction in a list request.

Ingest a record

queued = client.ingest_a_record(
    client_id="post-123", name="A post", entity="post", content="Hello",
)

Use ingest_a_record for asynchronous moderation. It returns a message, record id, nullable moderation ID, and optional user ID.

The final moderation outcome arrives through webhooks.

Moderate a record

from insion.types import ContentExternalUrls, UserInput

result = client.moderate_a_record(
    client_id="post-123", name="A post", entity="post",
    content=ContentExternalUrls(text="Review this", image_urls=["https://cdn.example.com/post.png"]),
    metadata={"source": "community"},
    user=UserInput(client_id="user-42", email="person@example.com"),
)

Use moderate_a_record when the caller needs a decision before continuing. It creates or updates the record and returns ModerateResponse with id, status, moderation, optional user, message, deprecated flagged, and category_ids.

Setting passthrough=True evaluates the content without retaining record or user content.

Delete a record

deleted = client.delete_a_record(client_id="post-123")

Use delete_a_record when content no longer exists in your application. It expects your record client_id, not an Insion ID, and returns a success message.

List records

page = client.list_records(limit=100, entity="post", status="Flagged")
while page.has_more and page.data:
    page = client.list_records(limit=100, starting_after=page.data[-1].id)

Use list_records for queues, audits, and filtered searches. Filters are client_id, Insion user, entity, and status; use either starting_after or ending_before, never both. The result contains data and has_more.

Retrieve a record

record = client.retrieve_a_record("rec_123").data

Use retrieve_a_record when you know one Insion record ID and need its latest stored and moderation state. The record includes identifiers, URL, name/entity, protection and moderation state, metadata, timestamps, and optional user ID.

Ingest a user

created = client.ingest_a_user(
    client_id="user-42", email="person@example.com", name="Ada", protected=False,
)

Use ingest_a_user to create or update a user without attaching a record. It returns a success message and the Insion user ID used by later retrieval, filters, and appeals.

List users

users = client.list_users(limit=50, status="Suspended")

Use list_users for user-review queues and filtered searches by client_id, email, status, or Insion user; pagination matches records. The result contains data and has_more.

Retrieve a user

user = client.retrieve_a_user("usr_123").data

Use retrieve_a_user for one known Insion user ID. The returned user includes profile fields, protection state, metadata, action status/timestamp, and nullable appeal URL.

Create an appeal

appeal = client.create_an_appeal("usr_123", text="Please review this decision.")

Use create_an_appeal after an eligible suspended user requests a review. The positional ID is the Insion user ID, and appeals must be enabled. CreateAppealResponse.data includes the appeal ID, action state, timestamps, and nullable appeal URL.

On this page