Use Cases

Review the following sections to create requests for specific use cases, including:

Searching the Archive for a specific custodian

For eDiscovery investigations, AI Assistant can search your archived communications and answer questions about a specific custodian’s messages, including counts, themes, and timelines.

In this tutorial, you will:

  • Use the archive_search tool to find messages from a specific person.
  • Ask targeted questions about a custodian’s communications.
  • Retrieve and cite the source messages AI Assistant provided.

Create a conversation for the custodian search

Begin by creating a conversation, so you can ask follow-up questions and retain the full transcript for audit purposes:

curl -s -X POST "https://<api-host>/v1/conversations" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "id": "conv_a1b2c3d4",
  "object": "conversation",
  "created_at": 1725475200,
  "metadata": {}
}

Save the conv_… id for the subsequent steps.

Ask for message counts from a specific custodian

Ask AI Assistant to search the Archive for a specific custodian’s messages within a specific case:

curl -N -X POST "https://<api-host>/v1/responses" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": true,
    "conversation": "conv_a1b2c3d4",
    "input": "How many messages were sent from Andrea Lacey in the Lautner Wealth Merger case? Include the date range of those messages.",
    "tools": [
      { "type": "archive_search" }
    ]
  }'

The output_text content may include url_citation annotations pointing to the source messages.

Ask follow-up questions about the custodian’s communications

Because you included the conversation id, AI Assistant has context from the prior turn, helping you ask targeted follow-up questions:

curl -N -X POST "https://<api-host>/v1/responses" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": true,
    "conversation": "conv_a1b2c3d4",
    "input": "Were any of those messages sent outside of business hours? If so, how many and on which dates?",
    "tools": [
      { "type": "archive_search" }
    ]
  }'

Ask for message content

Ask for even more granular information into the specific content of the custodian’s messages:

curl -N -X POST "https://<api-host>/v1/responses" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": true,
    "conversation": "conv_a1b2c3d4",
    "input": "Show me the content of the messages Andrea Lacey sent on February 14. Who were the recipients?",
    "tools": [
      { "type": "archive_search" }
    ]
  }'

Retrieve the full conversation transcript for your records

For audit and chain-of-custody purposes, export the full transcript of the conversation:

curl -s -X GET "https://<api-host>/v1/conversations/conv_a1b2c3d4/items?limit=100&order=asc" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response:

{
  "object": "list",
  "data": [
    {
      "id": "msg_000",
      "type": "message",
      "role": "user",
      "content": [
        { "type": "input_text", "text": "How many messages were sent from Andrea Lacey in the Lautner Wealth Merger case? Include the date range of those messages." }
      ],
      "status": "completed"
    },
    {
      "id": "msg_001",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Andrea Lacey sent 47 messages related to the Lautner Wealth Merger between January 15 and March 3, 2026. Of those, 12 were sent outside business hours (after 6 PM or before 8 AM local time) on the following dates: Jan 22, Jan 29, Feb 3, Feb 14, Feb 17, and Feb 28.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "grn://archive/arc_7f3a/msg/0042ab",
              "title": "RE: Lautner merger timeline",
              "start_index": 0,
              "end_index": 120
            }
          ]
        }
      ],
      "status": "completed"
    }
  ],
  "first_id": "msg_000",
  "last_id": "msg_001",
  "has_more": false
}

Identifying compliance risks in communications

Compliance teams often need to assess whether communications violate regulatory frameworks such as FINRA, SEC, MiFID II, or internal policies. By using AI Assistant’s reasoning model, you can perform a deeper analysis on these frameworks, where the generated reasoning items in the response show its analytical steps, alongside the final message item with its answer.

Set reasoning.effort to medium or high to route the request to the reasoning model. Use minimal or omit the field for standard, faster responses. For more information on which model to use, see Using Reasoning vs Standard Models.

In this tutorial, you will:

  • Use the reasoning model to analyze communications for regulatory risk
  • Ask the assistant to evaluate messages against specific regulatory frameworks
  • Review reasoning items to understand the assistant’s analysis
  • Drill into specific risks with follow-up questions

Create a conversation for the compliance analysis

curl -s -X POST "https://<api-host>/v1/conversations" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'

Save the conv_… id for the subsequent steps.

Request a compliance risk analysis

Ask the assistant to evaluate messages against specific regulatory frameworks. If necessary, use effort: "high" for complex multi-step analysis:

curl -N -X POST "https://<api-host>/v1/responses" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": true,
    "conversation": "conv_b2c3d4e5",
    "input": "Analyze all messages from Andrea Lacey related to the Lautner Wealth Merger case. Identify any potential compliance risks under FINRA Rule 3110 (supervision), SEC Rule 17a-4 (recordkeeping), and MiFID II Article 16 (recording of communications). Flag any messages that suggest pre-arranged trading, off-channel communications, or failure to supervise.",
    "reasoning": {
      "effort": "high"
    },
    "tools": [
      { "type": "archive_search" }
    ]
  }'

Review the reasoning and analysis

After the stream completes, review the response to see the full output including reasoning items:

curl -s -X GET "https://<api-host>/v1/responses/resp_m1n2o3p4" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response:

{
  "id": "resp_m1n2o3p4",
  "object": "response",
  "status": "completed",
  "created_at": 1725475400,
  "conversation": { "id": "conv_b2c3d4e5" },
  "output": [
    {
      "id": "rs_001",
      "type": "reasoning",
      "summary": [],
      "content": [
        { "type": "reasoning_text", "text": "Evaluating FINRA Rule 3110: reviewing whether supervisory review was documented for messages concerning the merger timeline..." }
      ],
      "status": "completed"
    },
    {
      "id": "msg_001",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "I identified the following potential compliance risks in Andrea Lacey's messages:\n\n1. FINRA Rule 3110 (Supervision): 3 messages dated Jan 22, Feb 3, and Feb 14 reference approval of the merger timeline without evidence of supervisory review.\n\n2. SEC Rule 17a-4 (Recordkeeping): 2 messages dated Feb 17 and Feb 28 appear to reference communications conducted via a personal channel not captured in the archive.\n\n3. MiFID II Article 16: No direct violations identified, but 4 messages reference phone calls for which no corresponding voice recording was found.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "grn://archive/arc_7f3a/msg/0042ab",
              "title": "RE: Lautner merger timeline",
              "start_index": 0,
              "end_index": 85
            },
            {
              "type": "url_citation",
              "url": "grn://archive/arc_7f3a/msg/0058cd",
              "title": "FW: Quick question about the merger",
              "start_index": 86,
              "end_index": 180
            }
          ]
        }
      ],
      "status": "completed"
    }
  ],
  "reasoning": { "effort": "high", "summary": null },
  "usage": {
    "input_tokens": 1850,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 420,
    "output_tokens_details": { "reasoning_tokens": 280 },
    "total_tokens": 2270
  }
}

The output array contains two items:

  1. Reasoning item (rs_001): Shows the AI Assistant reasoning process, where the reasoning_text content outlines how it evaluated each regulatory framework against the messages.
  2. Message item (msg_001): Contains the answer along with citations that link directly to the specific source messages it was based on.

Investigate a specific risk

Ask a follow-up question for more details:

curl -N -X POST "https://<api-host>/v1/responses" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": true,
    "conversation": "conv_b2c3d4e5",
    "input": "Show me the exact content of the 2 messages that reference off-channel communications. What specific language suggests they were conducted outside of approved channels?",
    "reasoning": {
      "effort": "medium"
    },
    "tools": [
      { "type": "archive_search" }
    ]
  }'

Request a risk summary

Ask AI Assistant to rank the risks by severity for a compliance report:

curl -N -X POST "https://<api-host>/v1/responses" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": true,
    "conversation": "conv_b2c3d4e5",
    "input": "Rank the compliance risks you identified by severity. For each, explain the potential regulatory consequence and recommend a next step for the compliance team.",
    "reasoning": {
      "effort": "high"
    },
    "tools": [
      { "type": "archive_search" }
    ]
  }'

Building a compliance audit trail

For eDiscovery and compliance, maintaining a defensible audit trail is critical, because you must demonstrate not just what was found, but who requested it, when it happened, what questions were asked, etc.

AI Assistant API supports these findings through the following information:

  • metadata: A client-owned key/value store on each response, returned exactly as it was submitted. Use this information to tag requests with matter numbers, custodian names, reviewer identities, and legal hold references.
  • Input items: The exact questions that were submitted with each answer, so you can verify precisely what was asked.
  • Conversation transcript: The full ordered history of questions and answers, with url_citation annotations pointing to source messages.

Together, these can help form a complete chain of relevant information.

In this tutorial, you will:

  • Attach metadata to responses for matter tracking and audit purposes
  • Retrieve response input items to verify exactly what was asked
  • Compile a complete audit trail across a conversation

Create a conversation tagged to a matter

curl -s -X POST "https://<api-host>/v1/conversations" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'

Save the conv_… id.

Send a request with audit metadata

Tag every response with matter and custodian metadata so it is preserved in the response:

curl -N -X POST "https://<api-host>/v1/responses" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": true,
    "conversation": "conv_c3d4e5f6",
    "input": "List all messages exchanged between Andrea Lacey and Alex Steadman regarding the Lautner Wealth Merger between January 1 and March 31, 2026. Include dates, subjects, and whether any were marked as high priority.",
    "tools": [
      { "type": "archive_search" }
    ],
    "metadata": {
      "matter": "Lautner-2026-ED-0042",
      "custodian": "Andrea Lacey",
      "reviewer": "Tim Garcia",
      "purpose": "ediscovery-custodian-search",
      "legal_hold": "LH-2026-017"
    }
  }'

Retrieve the response with the metadata

curl -s -X GET "https://<api-host>/v1/responses/resp_q1r2s3t4" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response:

{
  "id": "resp_q1r2s3t4",
  "object": "response",
  "status": "completed",
  "created_at": 1725475500,
  "conversation": { "id": "conv_c3d4e5f6" },
  "output": [
    {
      "id": "msg_001",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "I found 23 messages exchanged between Andrea Lacey and Alex Steadman regarding the Lautner Wealth Merger between January 1 and March 31, 2026...",
          "annotations": [
            {
              "type": "url_citation",
              "url": "grn://archive/arc_7f3a/msg/0042ab",
              "title": "RE: Lautner merger timeline",
              "start_index": 0,
              "end_index": 95
            }
          ]
        }
      ],
      "status": "completed"
    }
  ],
  "metadata": {
    "matter": "Lautner-2026-ED-0042",
    "custodian": "Andrea Lacey",
    "reviewer": "Tim Garcia",
    "purpose": "ediscovery-custodian-search",
    "legal_hold": "LH-2026-017"
  },
  "usage": {
    "input_tokens": 920,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 310,
    "output_tokens_details": { "reasoning_tokens": 0 },
    "total_tokens": 1230
  }
}

The metadata you submitted is returned in the response, preserving the context exactly as you provided it.

Verify the input items for chain of custody

Confirm exactly what question was asked for this response:

curl -s -X GET "https://<api-host>/v1/responses/resp_q1r2s3t4/input_items?limit=20&order=asc" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response:

{
  "object": "list",
  "data": [
    {
      "id": "msg_000",
      "type": "message",
      "role": "user",
      "content": [
        { "type": "input_text", "text": "List all messages exchanged between Andrea Lacey and Alex Steadman regarding the Lautner Wealth Merger between January 1 and March 31, 2026. Include dates, subjects, and whether any were marked as high priority." }
      ],
      "status": "completed"
    }
  ],
  "first_id": "msg_000",
  "last_id": "msg_000",
  "has_more": false
}

Export the full audit trail

Retrieve the complete conversation transcript, including every question, answer, and citation:

curl -s -X GET "https://<api-host>/v1/conversations/conv_c3d4e5f6/items?limit=100&order=asc" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

The transcript, combined with the metadata on each response and the input items, helps form a complete audit trail record:

Audit elementWhere it resides
What was askedGET /v1/responses/{id}/input_items
What was answeredoutput array on the response object
Who requested it and whymetadata on each response
When was it runcreated_at timestamp on each response
What sources were usedurl_citation annotations in output_text parts
Full question/answer historyGET /v1/conversations/{id}/items