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.

Examples use api := client.NewClient(...), ctx, and the root package aliased as insion. Trailing option.RequestOption values are optional.

Shared models

Record

Field	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	`&insion.Content{String: "text"}`, or structured 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

Field	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.

Optional values

Value type	Helper
Integer	`insion.Int`
String	`insion.String`
Boolean	`insion.Bool`

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, err := api.IngestARecord(ctx, &insion.RecordInput{
    ClientID: "post-123", Name: "A post", Entity: "post",
    Content: &insion.Content{String: "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, err := api.ModerateARecord(ctx, &insion.ModerateRequest{
    ClientID: "post-123", Name: "A post", Entity: "post",
    Content: &insion.Content{String: "Hello world"},
    Metadata: map[string]any{"source": "community"},
})

Use ModerateARecord 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.

Setting Passthrough: insion.Bool(true) evaluates the content without retaining record or user content.

Delete a record

deleted, err := api.DeleteARecord(ctx, &insion.DeleteAPIV1IngestRequest{ClientID: "post-123"})

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

List records

page, err := api.ListRecords(ctx, &insion.GetAPIV1RecordsRequest{Limit: insion.Int(100)})

Use ListRecords for review queues, audits, and filtered searches by client ID, Insion user ID, entity, or status. Use only one of StartingAfter or EndingBefore; pages contain Data and HasMore.

Retrieve a record

record, err := api.RetrieveARecord(ctx, &insion.GetAPIV1RecordsRecordIDRequest{RecordID: "rec_123"})

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, err := api.IngestAUser(ctx, &insion.UserInput{ClientID: "user-42", Email: insion.String("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, err := api.ListUsers(ctx, &insion.GetAPIV1UsersRequest{Limit: insion.Int(50)})

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

Retrieve a user

user, err := api.RetrieveAUser(ctx, &insion.GetAPIV1UsersUserIDRequest{UserID: "usr_123"})

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, err := api.CreateAnAppeal(ctx, &insion.PostAPIV1UsersUserIDCreateAppealRequest{
    UserID: "usr_123", Text: "Please review this decision.",
})

Use CreateAnAppeal after an eligible suspended user requests a review. The request uses an Insion user ID, and appeals must be enabled. The response includes appeal/action state, timestamps, and nullable appeal URL.

On this page