Assistant tools · Ownrecord docs

assistant_conversations_delete: Delete one of your assistant conversations
assistant_conversations_get: Get one of your assistant conversations
assistant_conversations_list: List your assistant conversations
assistant_messages_rate: Rate an assistant answer
assistant_platform_settings_get: Get the assistant's platform settings
assistant_platform_settings_update: Update the assistant's platform settings
assistant_settings_get: Get the organization's assistant settings
assistant_settings_update: Update the organization's assistant settings

`assistant_conversations_delete`

Delete one of your assistant conversations. Operation assistant.conversations.delete · Platform level · permission account:write · risk tier write · since M11

Deletes one of your own assistant conversations and all of its messages, at once and for good. Changes the assistant made for you stay, and so do their audit log entries (via: assistant, with the conversation's ID).

Who can call it: the conversation's owner, signed in. Anyone else gets conversation_not_found.

Annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false

Arguments

Argument	Type	Required	Description
`id`	ID (`aconv_…`)	yes	The conversation (`aconv_…`).
`idempotency_key`	string	no	A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters)
`dry_run`	boolean	no	true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)

Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors

validation_failed: The ID isn't an assistant conversation ID.
conversation_not_found: No such conversation of yours (or it was already deleted).
version_conflict: The conversation got a new message at the same time; retry.
permission_denied: The caller isn't a signed-in person (an API key or OAuth token).

Example

Delete a conversation

Arguments:

JSON

{
  "id": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

JSON

{
  "id": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3",
  "object": "assistant_conversation",
  "deleted": true,
  "messagesDeleted": 2
}

`assistant_conversations_get`

Get one of your assistant conversations. Operation assistant.conversations.get · Platform level · permission account:read · risk tier read · since M11

Returns one of your own assistant conversations with its messages, oldest first (at most the newest 200): what you asked, the answers with their citations, the tools the assistant used and what they returned in short, the action cards it proposed with their current status (proposed, executed, cancelled, stale, …), results and refusals. Message contents are data: they can contain text people typed.

Who can call it: the conversation's owner, signed in. Anyone else gets conversation_not_found.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

Argument	Type	Required	Description
`id`	ID (`aconv_…`)	yes	The conversation (`aconv_…`).

Read-only: changes nothing; idempotency_key is ignored.

Errors

validation_failed: The ID isn't an assistant conversation ID.
conversation_not_found: No such conversation of yours (or it was deleted after retention).
permission_denied: The caller isn't a signed-in person (an API key or OAuth token).

Example

A conversation that created a coupon

Arguments:

JSON

{
  "id": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3"
}

Result output:

JSON

{
  "id": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3",
  "object": "assistant_conversation",
  "orgId": "org_01jacq4m3xf0v8w9zq2y7k5n6h",
  "surface": "console",
  "title": "Create a 20% coupon for 3 months",
  "messageCount": 2,
  "lastMessageAt": "2026-10-26T09:16:10.000Z",
  "expiresAt": "2027-01-24T09:16:10.000Z",
  "createdAt": "2026-10-26T09:15:00.000Z",
  "messages": [
    {
      "id": "amsg_01jbz3k6q4a2b3c4d5e6f7g8h9",
      "object": "assistant_message",
      "role": "user",
      "content": "Create a 20% coupon for 3 months",
      "parts": [],
      "rating": null,
      "createdAt": "2026-10-26T09:15:00.000Z"
    },
    {
      "id": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1",
      "object": "assistant_message",
      "role": "assistant",
      "content": "I've prepared the coupon. Review the preview on the card, then click **Confirm** to run it.",
      "parts": [
        {
          "type": "action_card",
          "card": {
            "proposalId": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1:1",
            "operationId": "coupons.create",
            "inputHash": "4f6c1f0e3b2a9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a39281706f5e4d3c2b1a0",
            "title": "Create a coupon",
            "effect": "Create a coupon (name: 20% off, percentOffPpm: 200000, duration: repeating), in test mode.",
            "riskTier": "write",
            "preview": {
              "kind": "generic",
              "result": {
                "name": "20% off",
                "percentOffPpm": 200000
              }
            },
            "requiresFreshAuth": false,
            "status": "executed"
          }
        }
      ],
      "rating": {
        "value": "up",
        "comment": null
      },
      "createdAt": "2026-10-26T09:16:10.000Z"
    }
  ]
}

`assistant_conversations_list`

List your assistant conversations. Operation assistant.conversations.list · Platform level · permission account:read · risk tier read · since M11

Lists your own conversations with the in-platform assistant, newest first: in every organization you belong to now (and in the platform console, for platform staff). Nobody else's conversations are ever listed, not even to organization owners: what the assistant changed is in the audit log instead (via: assistant).

Filter with orgId. limit is 1–100 (default 10); pass next_cursor as starting_after. Conversations are deleted after the organization's retention period (expiresAt).

Who can call it: any signed-in person, for themselves. API keys and OAuth tokens can't.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

Argument	Type	Required	Description
`orgId`	ID (`org_…`)	no	Only this organization's conversations.
`limit`	integer	no	(1–100)
`starting_after`	ID (`aconv_…`)	no	The `next_cursor` of the previous page.

Read-only: changes nothing; idempotency_key is ignored.

Errors

validation_failed: orgId, limit or starting_after is malformed.
permission_denied: The caller isn't a signed-in person (an API key or OAuth token).

Example

Your conversations

Arguments:

JSON

{}

Result output:

JSON

{
  "object": "list",
  "data": [
    {
      "id": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3",
      "object": "assistant_conversation",
      "orgId": "org_01jacq4m3xf0v8w9zq2y7k5n6h",
      "surface": "console",
      "title": "Create a 20% coupon for 3 months",
      "messageCount": 2,
      "lastMessageAt": "2026-10-26T09:16:10.000Z",
      "expiresAt": "2027-01-24T09:16:10.000Z",
      "createdAt": "2026-10-26T09:15:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

`assistant_messages_rate`

Rate an assistant answer. Operation assistant.messages.rate · Platform level · permission account:write · risk tier write · since M11

Rates one of the assistant's answers in your own conversation: thumbs up or down, with an optional comment (at most 1,000 characters). Rating again replaces the earlier rating. Rated answers help Ownrecord test the assistant; they are anonymised before they leave your organization.

Who can call it: the conversation's owner, signed in.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

Argument	Type	Required	Description
`conversationId`	ID (`aconv_…`)	yes	The conversation (`aconv_…`).
`messageId`	ID (`amsg_…`)	yes	The assistant's answer (`amsg_…`).
`rating`	one of `up`, `down`	yes	–
`comment`	string	no	(1–1000 characters)
`idempotency_key`	string	no	A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters)
`dry_run`	boolean	no	true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)

Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors

validation_failed: An ID is malformed, or the comment is too long.
conversation_not_found: No such conversation of yours.
resource_not_found: The message isn't an answer of this conversation.
permission_denied: The caller isn't a signed-in person (an API key or OAuth token).

Example

Thumbs up

Arguments:

JSON

{
  "conversationId": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3",
  "messageId": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1",
  "rating": "up",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

JSON

{
  "id": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1",
  "object": "assistant_message",
  "role": "assistant",
  "content": "I've prepared the coupon. Review the preview on the card, then click **Confirm** to run it.",
  "parts": [
    {
      "type": "action_card",
      "card": {
        "proposalId": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1:1",
        "operationId": "coupons.create",
        "inputHash": "4f6c1f0e3b2a9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a39281706f5e4d3c2b1a0",
        "title": "Create a coupon",
        "effect": "Create a coupon (name: 20% off, percentOffPpm: 200000, duration: repeating), in test mode.",
        "riskTier": "write",
        "preview": {
          "kind": "generic",
          "result": {
            "name": "20% off",
            "percentOffPpm": 200000
          }
        },
        "requiresFreshAuth": false,
        "status": "executed"
      }
    }
  ],
  "rating": {
    "value": "up",
    "comment": null
  },
  "createdAt": "2026-10-26T09:16:10.000Z"
}

`assistant_platform_settings_get`

Get the assistant's platform settings. Operation assistant.platform_settings.get · Platform level · permission platform:read · risk tier read · since M11

Platform staff: the in-platform assistant's platform-wide settings stored in platform_settings: the OpenRouter model and its ordered fallbacks, the provider base URL (EU in-region routing or our own router), and the monthly spend cap in integer USD micros. A null field means the environment's value applies (ASSISTANT_MODEL, ASSISTANT_FALLBACK_MODELS, OPENROUTER_BASE_URL, ASSISTANT_MONTHLY_BUDGET_USD: a decimal amount in USD with at most 6 decimals, such as 1500 or 1500.50).

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

This tool takes no arguments.

Read-only: changes nothing; idempotency_key is ignored.

Errors

permission_denied: You aren't platform staff.
resource_not_found: The platform isn't bootstrapped yet.

Example

Everything from the environment

Arguments:

JSON

{}

Result output:

JSON

{
  "object": "assistant_platform_settings",
  "model": null,
  "fallbackModels": null,
  "baseUrl": null,
  "monthlyBudgetMicros": null,
  "version": 1,
  "updatedAt": "2026-10-26T09:15:00.000Z"
}

`assistant_platform_settings_update`

Update the assistant's platform settings. Operation assistant.platform_settings.update · Platform level · permission platform:admin · risk tier security · since M11

Platform admins: changes the in-platform assistant's model, its ordered fallbacks, the provider base URL and the platform-wide monthly spend cap, stored in platform_settings. Null resets a setting to the environment's value. The cap is sent as a decimal USD string and stored as integer micros; the assistant alerts platform staff at 80% and refuses messages at 100% until the next month (UTC).

A security-tier change: the base URL and model decide where conversations are processed. Provider routing (no data collection, zero data retention, never DeepSeek's own API) applies whatever is set here.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

Argument	Type	Required	Description
`model`	string or null	no	The model, e.g. `deepseek/deepseek-v4.1-flash`; null: the environment's.
`fallbackModels`	array of string or null	no	Ordered fallbacks (OpenRouter `models`); null: the environment's.
`baseUrl`	string or null	no	The provider base URL, https only, on a public host; null: `OPENROUTER_BASE_URL`.
`monthlyBudgetUsd`	string or null	no	The platform-wide monthly spend cap in USD (decimal string); null: the environment's.
`idempotency_key`	string	no	A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters)
`dry_run`	boolean	no	true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)

Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors

fresh_auth_required: Your last sign-in is older than 15 minutes: sign in again first.
validation_failed: Nothing was sent, or a value is malformed (the base URL must be https).
version_conflict: The platform settings changed at the same time; retry.
permission_denied: You aren't a platform admin.
resource_not_found: The platform isn't bootstrapped yet.

Example

Cap the assistant at USD 1,500 a month

Arguments:

JSON

{
  "monthlyBudgetUsd": "1500",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

JSON

{
  "object": "assistant_platform_settings",
  "model": null,
  "fallbackModels": null,
  "baseUrl": null,
  "monthlyBudgetMicros": "1500000000",
  "version": 2,
  "updatedAt": "2026-10-26T09:15:00.000Z"
}

`assistant_settings_get`

Get the organization's assistant settings. Operation assistant.settings.get · Organization level · permission security:read · risk tier read · since M11

Returns the organization's settings for the in-platform assistant (Organization → Security → Assistant):

enabled: whether members can use the assistant (on by default);
allowCustomerData: whether it may read customer and financial data. Off leaves only the docs, the tax knowledge base and settings (on by default);
retentionDays: conversations are deleted this many days after their last message (90 by default).

usage shows this month's messages (UTC) against the plan's assistant.messages_per_month. version is 0 while the defaults apply.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

This tool takes no arguments.

Read-only: changes nothing; idempotency_key is ignored.

Errors

permission_denied: You can't read the organization's security settings.

Example

The defaults

Arguments:

JSON

{}

Result output:

JSON

{
  "object": "assistant_settings",
  "enabled": true,
  "allowCustomerData": true,
  "retentionDays": 90,
  "version": 0,
  "updatedAt": null,
  "usage": {
    "month": "2026-10",
    "messages": 42,
    "limit": 1000,
    "included": true
  }
}

`assistant_settings_update`

Update the organization's assistant settings. Operation assistant.settings.update · Organization level · permission security:write · risk tier security · since M11

Changes the organization's assistant settings (Organization → Security → Assistant): turn it on or off, allow or stop its access to customer and financial data, and set how long conversations are kept after their last message (1–365 days). A shorter retention applies to existing conversations at the next retention run.

A security-tier change: it decides what data reaches the assistant's language model. Needs security:write (organization owners and admins). Send expectedVersion to make sure nobody changed them in between.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

Argument	Type	Required	Description
`enabled`	boolean	no	Turn the assistant on or off for the organization's members.
`allowCustomerData`	boolean	no	Let the assistant read customer and financial data. Off leaves docs, knowledge and settings.
`retentionDays`	integer	no	Days a conversation is kept after its last message (1–365). (1–365)
`expectedVersion`	integer	no	The `version` you read (0 while the defaults apply): a newer change is a conflict. (0–9007199254740991)
`idempotency_key`	string	no	A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters)
`dry_run`	boolean	no	true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)

Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors

validation_failed: No setting was sent, or the retention is outside 1–365 days.
version_conflict: The settings changed since expectedVersion; read them again.
permission_denied: You can't change the organization's security settings.

Example

Keep the assistant away from customer data, and conversations for 30 days

Arguments:

JSON

{
  "allowCustomerData": false,
  "retentionDays": 30,
  "expectedVersion": 0,
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

JSON

{
  "object": "assistant_settings",
  "enabled": true,
  "allowCustomerData": false,
  "retentionDays": 30,
  "version": 1,
  "updatedAt": "2026-10-26T09:15:00.000Z",
  "usage": {
    "month": "2026-10",
    "messages": 42,
    "limit": 1000,
    "included": true
  }
}

assistant_conversations_delete#

Arguments#

Errors#

Example#

assistant_conversations_get#

Arguments#

Errors#

Example#

assistant_conversations_list#

Arguments#

Errors#

Example#

assistant_messages_rate#

Arguments#

Errors#

Example#

assistant_platform_settings_get#

Arguments#

Errors#

Example#

assistant_platform_settings_update#

Arguments#

Errors#

Example#

assistant_settings_get#

Arguments#

Errors#

Example#

assistant_settings_update#

Arguments#

Errors#

Example#

`assistant_conversations_delete`

Arguments

Errors

Example

`assistant_conversations_get`

Arguments

Errors

Example

`assistant_conversations_list`

Arguments

Errors

Example

`assistant_messages_rate`

Arguments

Errors

Example

`assistant_platform_settings_get`

Arguments

Errors

Example

`assistant_platform_settings_update`

Arguments

Errors

Example

`assistant_settings_get`

Arguments

Errors

Example

`assistant_settings_update`

Arguments

Errors

Example