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.

Every operation accepts Option<RequestOptions> last. Builders return a build error when required fields are absent.

Shared models

Record builders

Builder method	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	`Content::String`, or structured content with text and URLs.
`client_url(...)`	No	A link to the record in your application.
`metadata(...)`	No	Serializable application context.
`user(...)`	No	The user associated with the record.
`passthrough(...)`	Moderation only	Moderate without retaining record or user content.

User builder

Builder method	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. Builders return BuildError when a required field is absent.

Ingest a record

let queued = client.ingest_a_record(
    &IngestRecordRequest(
        RecordInput::builder()
            .client_id("post-123").name("A post").entity("post")
            .content(Content::String("Hello".into())).build()?
    ),
    None,
).await?;

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

let result = client.moderate_a_record(
    &ModerateRequest::builder()
        .client_id("post-123").name("A post").entity("post")
        .content(Content::String("Hello world".into()))
        .build()?,
    None,
).await?;

Use moderate_a_record when the caller needs a decision before continuing. It creates or updates the record and returns record ID, status, moderation ID, optional user ID, message, deprecated flagged value, and category IDs.

Enabling passthrough evaluates the content without retaining record or user content.

Delete a record

let deleted = client.delete_a_record(
    &DeleteApiV1IngestRequest::builder().client_id("post-123").build()?, None,
).await?;

Use delete_a_record when content no longer exists in your application. It expects your client ID and returns a success response.

List records

let page = client.list_records(
    &ListRecordsQueryRequest::builder().limit(100).entity("post").build()?, None,
).await?;

Use list_records for review queues, audits, and filtered searches by client ID, Insion user ID, entity, or status. Use only one cursor direction; pages contain data and has_more.

Retrieve a record

let record = client.retrieve_a_record("rec_123", None).await?.data;

Use retrieve_a_record for one known Insion record ID. The record contains identifiers, URL, name/entity, protection/moderation state, metadata, timestamps, and user ID.

Ingest a user

let created = client.ingest_a_user(
    &UserInput::builder().client_id("user-42").email("person@example.com").build()?, None,
).await?;

Use ingest_a_user to create or update a user independently of a record. It returns the Insion user ID used by later filters, retrieval, and appeals.

List users

let users = client.list_users(&ListUsersQueryRequest::builder().limit(50).build()?, None).await?;

Use list_users for review queues and filtered searches by client ID, email, action status, or Insion user ID.

Retrieve a user

let user = client.retrieve_a_user("usr_123", None).await?.data;

Use retrieve_a_user for one known Insion user ID. User models include profile/protection fields, metadata, timestamps, action state, and appeal URL.

Create an appeal

let appeal = client.create_an_appeal(
    "usr_123",
    &PostApiV1UsersUserIdCreateAppealRequest::builder()
        .text("Please review this decision.").build()?,
    None,
).await?;

Use create_an_appeal after an eligible suspended user requests a review. The first value is an Insion user ID, and appeals must be enabled. The response contains appeal/action state, timestamps, and nullable appeal URL.

On this page