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.

Methods use keyword arguments and return Insion::Types models.

Shared models

Record

Keyword	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 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

Keyword	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 the record ID, nullable moderation ID, optional user ID, and message.

The final moderation outcome arrives through webhooks.

Moderate a record

result = client.moderate_a_record(
  client_id: "post-123", name: "A post", entity: "post", content: "Hello world",
  metadata: { "source" => "community" },
  user: { 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 the record ID, Compliant/Flagged status, moderation ID, optional user ID, message, deprecated flagged boolean, 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 and returns a success response.

List records

page = client.list_records(limit: 100, entity: "post", status: "Flagged")
page = client.list_records(limit: 100, starting_after: page.data.last.id) if page.has_more

Use list_records for review queues, audits, and filtered searches by client ID, Insion user ID, entity, or status. Use only one of starting_after or ending_before; the result contains data and has_more.

Retrieve a record

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

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

Ingest a user

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

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

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

Use list_users for review queues and filtered searches by client ID, email, action status, or Insion user ID; cursor rules match records.

Retrieve a user

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

Use retrieve_a_user for one known Insion user ID. The user includes profile/protection data, metadata, timestamps, action state, and appeal URL.

Create an appeal

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

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

On this page