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 below are members of InsionClient. Each accepts an optional second RequestOptions argument.

Shared models

Record

User

Identifiers and pagination

Use only one cursor direction in a list request.

Ingest a record

const queued = await client.ingestARecord({
  clientId: "post-123",
  name: "A post",
  entity: "post",
  content: "Hello",
});

Use ingestARecord for asynchronous pipelines where your application does not wait for a moderation decision. It uses the shared Record and returns message, record id, nullable moderation, and optional user ID.

Moderate a record

const result = await client.moderateARecord({
  clientId: "post-123",
  clientUrl: "https://example.com/posts/123",
  name: "A post",
  entity: "post",
  content: {
    text: "Review this post",
    imageUrls: ["https://cdn.example.com/post.png"],
    externalUrls: ["https://example.com/source"],
  },
  metadata: { source: "community" },
  user: { clientId: "user-42", email: "person@example.com" },
});

Use moderateARecord when the caller must know whether content is compliant before continuing. It creates or updates the record and returns ModerateResponse: id, status (Compliant or Flagged), moderation, optional user, message, deprecated flagged, and categoryIds.

Delete a record

await client.deleteARecord({ clientId: "post-123" });

Use deleteARecord when content is removed from your application and should also be removed from Insion. The request uses your record clientId, not the Insion record ID, and returns a success message.

List records

let page = await client.listRecords({ limit: 100, entity: "post", status: "Flagged" });
while (page.has_more && page.data.length > 0) {
  page = await client.listRecords({ limit: 100, starting_after: page.data.at(-1)!.id });
}

Use listRecords for moderation queues, audits, or synchronizing stored records. Filters are clientId, Insion user, entity, and status. Pagination uses starting_after or ending_before; do not send both. The response contains data and has_more. Each record includes IDs, URL, name, entity, protection and moderation state, metadata, timestamps, and optional associated user ID.

Retrieve a record

const { data: record } = await client.retrieveARecord({ recordId: "rec_123" });

Use retrieveARecord when you already know one Insion record ID and need its current stored and moderation state. recordId comes from moderation, ingestion, or listing; the response wraps the record in data.

Ingest a user

const user = await client.ingestAUser({
  clientId: "user-42",
  email: "person@example.com",
  name: "Ada",
  protected: false,
});

Use ingestAUser to create or update a user independently of a content record. The request accepts all shared user fields and returns a message plus the Insion user id; keep that ID for retrieval, filters, and appeals.

List users

const users = await client.listUsers({ limit: 50, status: "Suspended" });

Use listUsers to build user-review queues or find accounts by identity or action state. Filters are clientId, email, status, and Insion user. Cursor rules match record listing. Each user includes IDs, profile fields, protection state, metadata, timestamps, action status and timestamp, and nullable appealUrl.

Retrieve a user

const { data: user } = await client.retrieveAUser({ userId: "usr_123" });

Use retrieveAUser to load the latest state for one known user. The request uses an Insion user ID and the response wraps the complete user model in data.

Create an appeal

const { data: appeal } = await client.createAnAppeal({
  userId: "usr_123",
  text: "Please review this decision.",
});

Use createAnAppeal after an eligible suspended user submits a review request. Appeals must be enabled for the organization. The response contains the appeal id, action status and timestamp, creation/update timestamps, and nullable appealUrl.