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 accept an optional final options array.

Shared models

Record

Array key	Required	Purpose
`clientId`	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 and URLs.
`clientUrl`	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

Array key	Required	Purpose
`clientId`	Yes	Your stable identifier for the user.
`clientUrl`	No	A link to the user in your application.
`stripeAccountId`	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
`clientId`	Your application	Ingesting, moderating, and deleting.
`recordId`	Returned by Insion	Retrieving a record.
`userId`	Returned by Insion	Retrieving users and creating appeals.
`startingAfter` / `endingBefore`	Returned by Insion	Moving through list results.

Use only one cursor direction in a list request.

Ingest a record

$queued = $client->ingestARecord(new RecordInput([
    'clientId' => 'post-123', 'name' => 'A post', 'entity' => 'post', 'content' => 'Hello',
]));

Use ingestARecord 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

$result = $client->moderateARecord(new ModerateRequest([
    'clientId' => 'post-123', 'name' => 'A post', 'entity' => 'post',
    'content' => 'Hello world', 'metadata' => ['source' => 'community'],
]));

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

Setting passthrough in the request array evaluates the content without retaining record or user content.

Delete a record

$deleted = $client->deleteARecord(new DeleteApiV1IngestRequest(['clientId' => 'post-123']));

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

List records

$page = $client->listRecords(new GetApiV1RecordsRequest(['limit' => 100, 'entity' => 'post']));

Use listRecords 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 hasMore.

Retrieve a record

$record = $client->retrieveARecord('rec_123')?->data;

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

Ingest a user

$created = $client->ingestAUser(new UserInput(['clientId' => 'user-42', 'email' => 'person@example.com']));

Use ingestAUser 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->listUsers(new GetApiV1UsersRequest(['limit' => 50]));

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

Retrieve a user

$user = $client->retrieveAUser('usr_123')?->data;

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

Create an appeal

$appeal = $client->createAnAppeal(
    'usr_123',
    new PostApiV1UsersUserIdCreateAppealRequest(['text' => 'Please review this decision.']),
);

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

On this page