# Operations (/docs/sdks/swift/operations)



## Overview [#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 calls are `async throws` and accept optional `RequestOptions`.

## Shared models [#shared-models]

### Record [#record]

| Initializer argument | 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             | `.string("text")`, or structured content with text and URLs. |
| `clientUrl`          | No              | A link to the record in your application.                    |
| `metadata`           | No              | A `[String: JSONValue]` with application context.            |
| `user`               | No              | The user associated with the record.                         |
| `passthrough`        | Moderation only | Moderate without retaining record or user content.           |

### User [#user]

| Initializer argument | 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 [#identifiers-and-pagination]

<Callout type="info" title="Client IDs and Insion IDs">
  A client ID is supplied by your application, while an Insion ID is generated by Insion.
</Callout>

| 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 [#ingest-a-record]

```swift
let queued = try await client.ingestARecord(request: .init(
    clientId: "post-123", name: "A post", entity: "post", content: .string("Hello")
))
```

Use `ingestARecord` for asynchronous moderation. It returns a message, record ID, nullable moderation ID, and optional user ID.

<Callout type="info">
  The final moderation outcome arrives through webhooks.
</Callout>

## Moderate a record [#moderate-a-record]

```swift
let result = try await client.moderateARecord(request: .init(
    clientId: "post-123", name: "A post", entity: "post",
    content: .string("Hello world"),
    metadata: ["source": .string("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.

<Callout type="warn">
  Setting `passthrough: true` evaluates the content without retaining record or user content.
</Callout>

## Delete a record [#delete-a-record]

```swift
let deleted = try await client.deleteARecord(request: .init(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 [#list-records]

```swift
let page = try await client.listRecords(limit: 100, entity: "post", status: .flagged)
```

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 [#retrieve-a-record]

```swift
let record = try await client.retrieveARecord(recordId: "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 [#ingest-a-user]

```swift
let created = try await client.ingestAUser(request: .init(
    clientId: "user-42", email: "person@example.com", name: "Ada"
))
```

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 [#list-users]

```swift
let users = try await client.listUsers(limit: 50, status: .suspended)
```

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

## Retrieve a user [#retrieve-a-user]

```swift
let user = try await client.retrieveAUser(userId: "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 [#create-an-appeal]

```swift
let appeal = try await client.createAnAppeal(
    userId: "usr_123",
    request: .init(text: "Please review this decision.")
)
```

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