List conversation message branches

veryfront__list_conversation_message_branches

Access

No external-service connection is required. Use a Veryfront credential with access to the requested resources.

Call type: Read-only.

Arguments

FieldTypeRequiredDescription and constraints
conversation_idstringYesConversation identifier that scopes the request. Format: uuid.
message_idstringYesProvide the message id. Format: uuid.

Example request

Send this JSON-RPC request through an initialized MCP client. Replace sample identifiers and values before calling the tool. See MCP client setup.

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "veryfront__list_conversation_message_branches",
    "arguments": {
      "conversation_id": "00000000-0000-4000-8000-000000000000",
      "message_id": "00000000-0000-4000-8000-000000000000"
    }
  }
}

Result

The published output shape is summarized below. Inspect both the MCP response content and isError when handling a call.

FieldTypeRequiredDescription and constraints
dataobject[]YesMessage records for the requested page.
page_infoobjectYesPagination cursors for the message list.

Full schemas

json
{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "format": "uuid",
      "description": "Conversation identifier that scopes the request."
    },
    "message_id": {
      "type": "string",
      "format": "uuid",
      "description": "Provide the message id."
    }
  },
  "required": [
    "conversation_id",
    "message_id"
  ],
  "additionalProperties": false,
  "description": "Arguments for the list_conversation_message_branches tool.",
  "$schema": "http://json-schema.org/draft-07/schema#"
}
json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Message identifier."
          },
          "conversation_id": {
            "type": "string",
            "description": "Conversation identifier that owns the message."
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Parent message identifier when the message belongs to a branch or reply chain."
          },
          "seq": {
            "type": "number",
            "description": "Monotonic sequence number within the conversation."
          },
          "role": {
            "type": "string",
            "enum": [
              "user",
              "assistant",
              "tool"
            ],
            "description": "Message role such as user, assistant, tool, or system."
          },
          "created_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "User or actor identifier that created the message."
          },
          "sender_type": {
            "type": "string",
            "enum": [
              "user",
              "webhook",
              "service_account",
              "integration",
              "agent",
              "system"
            ],
            "description": "Sender kind: user, webhook, service_account, integration, agent or system.",
            "default": "user"
          },
          "sender_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Sender identifier: the participant or agent for an agent message, otherwise the author."
          },
          "sender_display_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Human-readable sender name when available."
          },
          "parts": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "text"
                    },
                    "text": {
                      "type": "string",
                      "maxLength": 100000
                    }
                  },
                  "required": [
                    "type",
                    "text"
                  ],
                  "additionalProperties": false,
                  "description": "Structured option 1 details associated with this tool result."
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "image"
                    },
                    "upload_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "media_type": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "upload_id",
                    "media_type"
                  ],
                  "additionalProperties": false,
                  "description": "Structured option 2 details associated with this tool result."
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "file"
                    },
                    "upload_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "media_type": {
                      "type": "string"
                    },
                    "filename": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "media_type"
                  ],
                  "additionalProperties": false,
                  "description": "Structured option 3 details associated with this tool result."
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "tool_call"
                    },
                    "id": {
                      "type": "string",
                      "description": "Unique identifier for the returned record."
                    },
                    "name": {
                      "type": "string",
                      "description": "Human-readable name for the returned record."
                    },
                    "input": {
                      "type": "object",
                      "additionalProperties": {
                        "description": "Additional structured values associated with this result."
                      },
                      "description": "Structured input details associated with this tool result."
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "streaming",
                        "pending",
                        "completed",
                        "error"
                      ]
                    }
                  },
                  "required": [
                    "type",
                    "id",
                    "name",
                    "input",
                    "state"
                  ],
                  "additionalProperties": false,
                  "description": "Structured option 4 details associated with this tool result."
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "tool_result"
                    },
                    "tool_call_id": {
                      "type": "string",
                      "description": "Tool call identifier associated with this result."
                    },
                    "output": {},
                    "is_error": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "type",
                    "tool_call_id"
                  ],
                  "additionalProperties": false,
                  "description": "Structured option 5 details associated with this tool result."
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "reasoning"
                    },
                    "text": {
                      "type": "string",
                      "maxLength": 100000
                    },
                    "signature": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "text"
                  ],
                  "additionalProperties": false,
                  "description": "Structured option 6 details associated with this tool result."
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "citation"
                    },
                    "source_id": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string",
                      "description": "Short human-readable title returned by the tool."
                    },
                    "quote": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "source_id"
                  ],
                  "additionalProperties": false,
                  "description": "Structured option 7 details associated with this tool result."
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "source_document"
                    },
                    "source_id": {
                      "type": "string"
                    },
                    "media_type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string",
                      "description": "Short human-readable title returned by the tool."
                    },
                    "filename": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "source_id",
                    "media_type",
                    "title"
                  ],
                  "additionalProperties": false,
                  "description": "Structured option 8 details associated with this tool result."
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "step_start"
                    }
                  },
                  "required": [
                    "type"
                  ],
                  "additionalProperties": false,
                  "description": "Structured option 9 details associated with this tool result."
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "error"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "code",
                    "message"
                  ],
                  "additionalProperties": false,
                  "description": "Structured option 10 details associated with this tool result."
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "data"
                    },
                    "name": {
                      "type": "string",
                      "description": "Human-readable name for the returned record."
                    },
                    "value": {}
                  },
                  "required": [
                    "type",
                    "name"
                  ],
                  "additionalProperties": false,
                  "description": "Structured option 11 details associated with this tool result."
                }
              ],
              "description": "One part item associated with this record."
            },
            "description": "Structured message parts, including text, tool invocations, or rich content blocks."
          },
          "model": {
            "type": [
              "string",
              "null"
            ],
            "description": "Model identifier that generated the message, when applicable."
          },
          "run_usage": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "funding": {
                    "type": "string",
                    "enum": [
                      "managed",
                      "customer",
                      "mixed"
                    ]
                  },
                  "capture_status": {
                    "type": "string",
                    "enum": [
                      "complete",
                      "partial",
                      "missing",
                      "unknown"
                    ]
                  },
                  "scope": {
                    "type": "string",
                    "const": "run"
                  },
                  "model": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "AI model id associated with this tool result."
                  },
                  "input_tokens": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "output_tokens": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "cache_creation_input_tokens": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "cache_read_input_tokens": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "reasoning_tokens": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "total_tokens": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "model_calls": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "cost_credits": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "scope",
                  "model",
                  "input_tokens",
                  "output_tokens",
                  "cache_creation_input_tokens",
                  "cache_read_input_tokens",
                  "reasoning_tokens",
                  "total_tokens",
                  "model_calls",
                  "cost_credits"
                ],
                "additionalProperties": false,
                "description": "Structured run usage details associated with this tool result."
              },
              {
                "type": "null",
                "description": "The run usage returned by the tool."
              }
            ],
            "description": "Token usage and cost of the whole run that produced an assistant message; absent when none is recorded."
          },
          "token_usage": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "input": {
                    "type": "number"
                  },
                  "output": {
                    "type": "number"
                  },
                  "reasoning_tokens": {
                    "type": "integer",
                    "minimum": 0
                  }
                },
                "additionalProperties": true,
                "description": "Structured token usage details associated with this tool result."
              },
              {
                "type": "null",
                "description": "The token usage returned by the tool."
              }
            ],
            "description": "Token accounting metadata associated with the message."
          },
          "finish_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Completion finish reason for model-generated messages."
          },
          "cost_credits": {
            "type": [
              "string",
              "null"
            ],
            "description": "Credit cost attributed to the message, when tracked."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "streaming",
              "completed",
              "failed",
              "cancelled"
            ],
            "description": "Lifecycle status of the message."
          },
          "edited_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Timestamp when the message was edited, or null when unedited."
          },
          "idempotency_key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Idempotency key used to deduplicate message creation requests."
          },
          "metadata": {
            "anyOf": [
              {
                "type": "object",
                "additionalProperties": {
                  "description": "Additional structured values associated with this result."
                },
                "description": "Additional structured metadata returned by the tool."
              },
              {
                "type": "null",
                "description": "Additional structured metadata returned by the tool."
              }
            ],
            "description": "Additional machine-readable message metadata."
          },
          "created_at": {
            "type": "string",
            "description": "Timestamp when the message was created."
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Timestamp when the message was last updated."
          }
        },
        "required": [
          "id",
          "conversation_id",
          "seq",
          "role",
          "parts",
          "status",
          "created_at"
        ],
        "additionalProperties": false,
        "description": "Conversation message record returned by MCP conversation tools."
      },
      "description": "Message records for the requested page."
    },
    "page_info": {
      "type": "object",
      "properties": {
        "self": {
          "type": [
            "string",
            "null"
          ],
          "description": "Cursor representing the current page."
        },
        "first": {
          "type": "null",
          "description": "Always null because these MCP pagination flows do not expose a first-page cursor."
        },
        "next": {
          "type": [
            "string",
            "null"
          ],
          "description": "Cursor for the next page, or null when there are no more results."
        },
        "prev": {
          "type": [
            "string",
            "null"
          ],
          "description": "Cursor for the previous page, or null when unavailable."
        }
      },
      "required": [
        "self",
        "first",
        "next",
        "prev"
      ],
      "additionalProperties": false,
      "description": "Pagination cursors for the message list."
    }
  },
  "required": [
    "data",
    "page_info"
  ],
  "additionalProperties": false,
  "description": "Paginated conversation message list response.",
  "$schema": "http://json-schema.org/draft-07/schema#"
}