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 have overloads accepting RequestOptions. Builders enforce required fields when .build() is called.

Shared models

Record builders

Builder method	Required	Purpose
`clientId(String)`	Yes	Your stable record identifier.
`name(String)`	Yes	A human-readable record title.
`entity(String)`	Yes	The record kind, such as `post` or `comment`.
`content(Content)`	Yes	`Content.of("text")`, or structured content with text and URLs.
`clientUrl(String)`	No	A link to the record in your application.
`metadata(Map)`	No	Serializable application context.
`user(UserInput)`	No	The user associated with the record.
`passthrough(boolean)`	Moderation only	Moderate without retaining record or user content.

User builder

Builder method	Required	Purpose
`clientId(String)`	Yes	Your stable identifier for the user.
`clientUrl(String)`	No	A link to the user in your application.
`stripeAccountId(String)`	No	The user's connected Stripe account ID.
`email(String)`	No	The user's email address.
`name(String)`	No	The user's display name.
`username(String)`	No	The user's handle in your application.
`protected_(boolean)`	No	Prevent automated moderation actions from affecting them.
`metadata(Map)`	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. Builders report missing required fields when build() is called.

Ingest a record

IngestRecordResponse queued = client.ingestARecord(
    RecordInput.builder().clientId("post-123").name("A post").entity("post")
        .content(Content.of("Hello")).build()
);

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

ModerateResponse result = client.moderateARecord(
    ModerateRequest.builder()
        .clientId("post-123").name("A post").entity("post")
        .content(Content.of("Hello world"))
        .build()
);

Use moderateARecord when the caller needs a decision before continuing. It creates or updates the record and returns its Insion ID, Compliant/Flagged status, moderation ID, optional user ID, message, deprecated flagged boolean, and matched category IDs.

Setting .passthrough(true) evaluates the content without retaining record or user content.

Delete a record

SuccessResponse deleted = client.deleteARecord(
    DeleteApiV1IngestRequest.builder().clientId("post-123").build()
);

Use deleteARecord when content no longer exists in your application. It expects your clientId, not the Insion record ID, and returns a success message.

List records

ListRecordsResponse page = client.listRecords(
    GetApiV1RecordsRequest.builder().limit(100).entity("post").status(GetApiV1RecordsRequestStatus.FLAGGED).build()
);

Use listRecords for queues, audits, and filtered searches by client ID, Insion user ID, entity, or status. Use either startingAfter or endingBefore; the result contains data and hasMore.

Retrieve a record

co.insion.types.Record record = client.retrieveARecord("rec_123").getData();

Use retrieveARecord when you know one Insion record ID and need its latest state. The record exposes IDs, URL, name/entity, protection and moderation state, metadata, timestamps, and associated user ID.

Ingest a user

IngestUserResponse created = client.ingestAUser(
    UserInput.builder().clientId("user-42").email("person@example.com").name("Ada").build()
);

Use ingestAUser to create or update a user independently of a record. The response contains a success message and the Insion user ID used for retrieval, filters, and appeals.

List users

ListUsersResponse users = client.listUsers(
    GetApiV1UsersRequest.builder().limit(50).build()
);

Use listUsers for review queues and filtered searches by client ID, email, action status, or Insion user ID; cursor rules match records. The result contains data and hasMore.

Retrieve a user

User user = client.retrieveAUser("usr_123").getData();

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

Create an appeal

CreateAppealResponse appeal = client.createAnAppeal(
    "usr_123",
    PostApiV1UsersUserIdCreateAppealRequest.builder().text("Please review this decision.").build()
);

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

On this page