> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://channel3.ferndocs.com/api-reference/api-reference/conversations/retrieve/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://channel3.ferndocs.com/_mcp/server.

# Get Conversation

GET https://api.trychannel3.com/v1/conversations/{conversation_id}

Thread metadata plus one page of its message history. Paginate `items` with `limit` and `cursor`.

Reference: https://channel3.ferndocs.com/api-reference/api-reference/conversations/retrieve

## Authentication

- `x-api-key` header (required) — API Key authentication via header
- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `conversation_id` (string, required)

### Query parameters

- `limit` (integer, optional, default: 50)
- `cursor` (string, optional, nullable)

## Response

### 200

Successful Response

- `id` (string, required)
- `created_at` (integer, required)
- `items` (list of ConversationDetailItemsItems, required)
- `user_id` (string, optional, nullable)
- `context` (ConversationContext, optional, nullable) — Partner-supplied context pinned to the top of a conversation thread.
- `next_cursor` (string, optional, nullable) — Pass as ``cursor`` to fetch the next page. Null when no more items.
- `has_more` (boolean, optional, default: false)

## Errors

### 400 Bad Request Error

Invalid cursor

- `detail` (string, required)

### 401 Unauthorized Error

Unauthorized

- `detail` (string, required)

### 402 Payment Required Error

Payment required

- `detail` (AppRoutersUtilsErrorResponseDetail, required)

### 404 Not Found Error

Conversation not found

- `detail` (string, required)

### 422 Unprocessable Entity Error

Request validation failed

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)
- `input` (any, optional)
- `ctx` (ValidationErrorCtx, optional)

### 429 Too Many Requests Error

Rate limit exceeded

- `detail` (string, required)

### 500 Internal Server Error

Internal server error

- `detail` (string, required)

## Types

### ConversationDetailItemsItems

- `role`: `assistant` (AssistantMessage)
  - `parts` (list of ConversationDetailItemsItemsDiscriminatorMappingAssistantPartsItems, optional)
  - `suggestions` (list of string, optional) — Tap-ready follow-up messages offered after this reply.
- `role`: `user` (UserMessage)
  - `parts` (list of UserMessagePartsItems, optional)

### ConversationContext

Partner-supplied context pinned to the top of a conversation thread.

- `user_context` (string, optional, nullable) — Who the conversation is with (profile, preferences, session facts).
- `application_context` (string, optional, nullable) — What platform or surface is hosting this conversation.

### AppRoutersUtilsErrorResponseDetail

### ValidationErrorLocItems

### ValidationErrorCtx

### ConversationDetailItemsItemsDiscriminatorMappingAssistantPartsItems

- `type`: `text` (TextPart)
  - `text` (string, required)
- `type`: `tool` (ToolPart)
  - `tool_call_id` (string, required)
  - `tool_name` (string, required)
  - `input` (PartStartedEventPartDiscriminatorMappingToolInput, optional)
  - `output` (PartStartedEventPartDiscriminatorMappingToolOutput, optional, nullable)

### UserMessagePartsItems

- `type`: `image` (ImagePart)
  - `url` (string, required)
- `type`: `text` (TextPart)
  - `text` (string, required)

### PartStartedEventPartDiscriminatorMappingToolInput

### PartStartedEventPartDiscriminatorMappingToolOutput

### SearchProductsInput

- `query` (string, required)

### ProductIdsInput

- `product_ids` (list of string, optional)

### CatalogDisplayPayload

Client-facing catalog tool result shown on the stream and on ``ToolPart``.

- `products` (list of Product, optional)
- `next_page_token` (string, optional, nullable)
- `api_call_id` (string, optional, nullable)

### CatalogToolError

- `error` (string, required)
- `is_error` (true, optional, default: true)
- `products` (list of Product, optional)

### Product

Product with detailed information.

- `id` (string, required)
- `title` (string, required)
- `description` (string, optional, nullable)
- `brands` (list of ProductBrand, optional) — Ordered list of brands.
- `images` (list of ProductImage, optional, default: [])
- `category` (CategorySummary, optional, nullable) — The single category this product belongs to, as a structured `CategorySummary` (slug, title, path, has_children).
- `gender` (enum, optional, nullable) — Product gender. 'unisex' is deprecated: coerced to None on input, never emitted.
  - Allowed values: `male`, `female`
- `age` (enum, optional, nullable) — Target age group. Age-agnostic products are typically returned as 'adult'.
  - Allowed values: `newborn`, `infant`, `toddler`, `kids`, `adult`
- `materials` (list of string, optional, nullable)
- `key_features` (list of string, optional, nullable)
- `offers` (list of ProductOffer, optional) — All merchant offers for this product in the requested locale.
- `variants` (Variants, optional, nullable) — Variant interaction state — options, selected. Absent when the product has no variations.
- `structured_attributes` (map from string to list of string, optional) — Structured attributes extracted for this product, keyed by attribute handle (e.g. 'color', 'material'). Values are the canonical allowed values for that handle.

### ProductBrand

- `id` (string, required)
- `name` (string, required)

### ProductImage

Product image with metadata.

- `url` (string, required)
- `cleaned_url` (string, optional, nullable) — Background-removed square image on Channel3 CDN when available. Use for product grids; ``url`` is the regular hosted shot.
- `is_main_image` (boolean, optional, default: false)
- `shot_type` (enum, optional, nullable) — Product image type classification for API responses.
  - Allowed values: `hero`, `lifestyle`, `on_model`, `detail`, `scale_reference`, `angle_view`, `flat_lay`, `in_use`, `packaging`, `size_chart`, `product_information`, `merchant_information`
- `alt_text` (string, optional, nullable)

### CategorySummary

Lean category representation used in search hits and list rows.

- `slug` (string, required) — URL-friendly slug (e.g. 'sofas')
- `title` (string, required) — Human-readable category title
- `has_children` (boolean, required) — Whether this category has subcategories
- `path` (list of CategoryRef, optional) — Hierarchical path as a structured list, root first; the last entry is this category itself

### ProductOffer

- `url` (string, required)
- `domain` (string, required)
- `price` (Price, required)
- `availability` (enum, required) — The two availability values the public API emits on offers. Internal ``AvailabilityStatus`` values are collapsed to these via ``AvailabilityStatus.to_api()``.
  - Allowed values: `InStock`, `OutOfStock`
- `condition` (enum, optional, nullable) — Condition of this merchant offer (new or used). Null when condition is unknown.
  - Allowed values: `new`, `used`
- `max_commission_rate` (double, optional, default: 0) — The maximum commission rate for the merchant, as a decimal fraction: 0 is no commission, 0.5 is 50% commission. 'Max' because the actual commission rate may be lower due to vendor-specific affiliate rules.
- `dimensions` (Dimensions, optional, nullable) — Physical dimensions of this offer. Null when unknown.

### Variants

Wrapper for variant-interaction state on a Product. Holds `options` and `selected`. `options` represent all of the configuration options for the product. `selected` represents the currently selected option values.

- `options` (list of VariantOption, required)
- `selected` (list of SelectedOption, required)

### CategoryRef

Lean reference to a category, used in path and children arrays.

- `slug` (string, required) — URL-friendly slug (e.g. 'sofas')
- `title` (string, required) — Human-readable category title

### Price

- `price` (double, required) — The current price of the product, including any discounts.
- `currency` (string, required) — The currency code of the product, like USD, EUR, GBP, etc.
- `compare_at_price` (double, optional, nullable) — The original price of the product before any discounts.

### Dimensions

Physical dimensions of a product offer. Members are null when unknown. Values are standardized to the supported unit set; a merchant-stated value whose unit is not one of those units is omitted rather than shown.

- `length` (LengthDimension, optional, nullable) — A length measurement, in one of the supported length units.
- `width` (LengthDimension, optional, nullable) — A length measurement, in one of the supported length units.
- `height` (LengthDimension, optional, nullable) — A length measurement, in one of the supported length units.
- `weight` (WeightDimension, optional, nullable) — A weight measurement, in one of the supported weight units.

### VariantOption

One dimension of a product family (e.g. 'Color', 'Size').

- `name` (string, required) — The name of the option (e.g. 'Color', 'Size')
- `values` (list of OptionValue, required) — The values of the option (e.g. ['Blue', 'Red', 'Green'])

### SelectedOption

One effective selection on a product, post server-side relaxation.

- `name` (string, required) — The name of the selected option (e.g. 'Color', 'Size')
- `label` (string, required) — The display value of the selected option (e.g. 'Blue', 'XL')

### LengthDimension

A length measurement, in one of the supported length units.

- `number` (double, required)
- `unit` (enum, required) — The unit from the request's dimension filters when one was given (the value is converted to it); otherwise the unit the merchant stated.
  - Allowed values: `mm`, `cm`, `m`, `in`, `ft`

### WeightDimension

A weight measurement, in one of the supported weight units.

- `number` (double, required)
- `unit` (enum, required) — The unit from the request's dimension filters when one was given (the value is converted to it); otherwise the unit the merchant stated.
  - Allowed values: `mg`, `g`, `kg`, `oz`, `lb`

### OptionValue

One value of one variant option (e.g. 'Blue' under 'Color')

- `label` (string, required) — The display value of the option value (e.g. 'Blue')
- `exists` (boolean, required) — Whether the option value exists on the product, or is a configuration only present on another variant of the same product. For example, a shirt that comes in multiple colors, but only one color is available in Size XL.
- `available` (enum, optional, nullable) — The availability status of the option value. None when returned on search results, hydrated only on get product detail requests.
  - Allowed values: `InStock`, `OutOfStock`
- `thumbnail_url` (string, optional, nullable) — For options that reference different products, this is the URL of the thumbnail image for the option value. E.g., a shoe that comes in multiple colors will have an OptionValue for each color with a thumbnail_url set.
- `product_id` (string, optional, nullable) — The product id that represents this value. Variants that point to different products will have this field set, as well as thumbnail_url for displaying selector icons.

## Examples

**Response**

```json
{
  "id": "string",
  "created_at": 1,
  "items": [
    {
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "string"
        }
      ]
    }
  ],
  "user_id": "string",
  "context": {
    "user_context": "string",
    "application_context": "string"
  },
  "next_cursor": "string",
  "has_more": false
}
```

**SDK Code**

```python
import requests

url = "https://api.trychannel3.com/v1/conversations/conversation_id"

headers = {"x-api-key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.trychannel3.com/v1/conversations/conversation_id';
const options = {method: 'GET', headers: {'x-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trychannel3.com/v1/conversations/conversation_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.trychannel3.com/v1/conversations/conversation_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.trychannel3.com/v1/conversations/conversation_id")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.trychannel3.com/v1/conversations/conversation_id', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.trychannel3.com/v1/conversations/conversation_id");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["x-api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.trychannel3.com/v1/conversations/conversation_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```