Capture Interactions and Messages

Send us your AI conversations so we can analyze them for you. Works with everything from simple chatbots to complex agentic systems.

Getting Started (Simple Chat): Just provide the role (“user”, “assistant”, or “system”) and content for each message, along with an externalConversationId and your productId. That’s it!

Advanced Usage (Agentic Workflows): Capture the full execution trace of your AI agents using messageType for tool calls, thoughts, observations, and more. Include structured data via input/output fields to track what your agents are doing.

Key Features:

• Automatic Ordering: Messages are stored with sequential timestamps, or provide your own createdAt timestamps for historical data.
• Threading: Create nested conversations by referencing parent messages using parentMessageId or parentExternalMessageId.
• Organization Tracking: Associate users with organizations via externalOrganizationId. We’ll create the organization automatically if it doesn’t exist.
• Automatic De-duplication: Messages with an externalMessageId that already exists in the conversation are automatically skipped. This allows you to safely resend a batch of messages with new messages appended — previously ingested messages will be deduplicated and only new messages will be inserted. Each message in the response includes a status field (“created” or “deduplicated”) so you know what happened.

Perfect for understanding how your AI is performing in production and identifying areas for improvement.

POST /messages

cURL

cURL

curl --request POST \
  --url https://www.greenflash.ai/api/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalUserId": "user-123",
  "externalOrganizationId": "org-789",
  "externalConversationId": "conv-456",
  "productId": "123e4567-e89b-12d3-a456-426614174001",
  "versionId": "123e4567-e89b-12d3-a456-426614174003",
  "model": "gpt-greenflash-1",
  "properties": {
    "campaign": "summer-sale"
  },
  "systemPrompt": {
    "promptId": "123e4567-e89b-12d3-a456-426614174004",
    "components": [
      {
        "content": "You are a helpful assistant.",
        "type": "system",
        "source": "customer"
      }
    ]
  },
  "messages": [
    {
      "externalMessageId": "user-msg-1",
      "role": "user",
      "content": "Hello!"
    },
    {
      "externalMessageId": "assistant-msg-1",
      "role": "assistant",
      "content": "Hi there! How can I help you?"
    },
    {
      "externalMessageId": "tool-call-1",
      "messageType": "tool_call",
      "content": "Calling search tool",
      "toolName": "web_search",
      "input": {
        "query": "weather forecast"
      }
    },
    {
      "externalMessageId": "tool-result-1",
      "messageType": "observation",
      "content": "Search completed",
      "output": {
        "results": [
          "Sunny, 75°F"
        ]
      },
      "parentExternalMessageId": "tool-call-1"
    },
    {
      "externalMessageId": "final-1",
      "messageType": "final_response",
      "content": "Based on the search, today will be sunny with a high of 75°F."
    }
  ]
}
'

200

{
  "success": true,
  "conversationId": "123e4567-e89b-12d3-a456-426614174000",
  "systemPromptPromptId": "123e4567-e89b-12d3-a456-426614174004",
  "systemPromptComponentIds": [
    "123e4567-e89b-12d3-a456-426614174005",
    "123e4567-e89b-12d3-a456-426614174006"
  ],
  "messages": [
    {
      "messageId": "msg-001",
      "externalMessageId": "user-msg-1",
      "messageType": "user_message",
      "status": "created"
    },
    {
      "messageId": "msg-002",
      "externalMessageId": "assistant-msg-1",
      "messageType": "assistant_message",
      "status": "created"
    },
    {
      "messageId": "msg-003",
      "externalMessageId": "tool-call-1",
      "messageType": "tool_call",
      "status": "created"
    },
    {
      "messageId": "msg-004",
      "externalMessageId": "tool-result-1",
      "messageType": "observation",
      "status": "created"
    },
    {
      "messageId": "msg-005",
      "externalMessageId": "final-1",
      "messageType": "final_response",
      "status": "created"
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request payload for logging conversations and messages.

externalUserId · string · required

Your external user ID that will be mapped to a user in our system.

messages · object[] · required

Array of conversation messages.

Minimum array length: 1

Show child attributes

productId · string<uuid>

The Greenflash product this conversation belongs to. Either conversationId, externalConversationId, productId must be provided.

conversationId · string<uuid>

The Greenflash conversation ID. When provided, updates an existing conversation instead of creating a new one. Either conversationId, externalConversationId, productId must be provided.

externalConversationId · string

Your external identifier for the conversation. Either conversationId, externalConversationId, productId must be provided.

externalOrganizationId · string

Your unique identifier for the organization this user belongs to. If provided, the user will be associated with this organization.

model · string

The AI model used for the conversation.

properties · object

Additional data about the conversation.

Show child attributes

systemPrompt · string object

System prompt for the conversation. Can be a simple string or a prompt object with components.

Minimum string length: 1

sampleRate · number

Controls the percentage of requests that are ingested (0.0 to 1.0). For example, 0.1 means 10% of requests will be stored. Defaults to 1.0 (all requests ingested). Sampling is deterministic based on conversation ID.

Required range: 0 <= x <= 1

forceSample · boolean

When true, bypasses sampling and ensures this request is always ingested regardless of sampleRate. Use for critical conversations that must be captured.

Response

200

application/json

Messages logged successfully

Success response for message logging.

success · boolean · required

Whether the API call was successful.

conversationId · string<uuid> · required

The ID of the conversation that was created or updated.

systemPromptPromptId · string<uuid> · required

The prompt ID used internally to track the system prompt.

systemPromptComponentIds · string<uuid>[] · required

The component IDs used internally to track the system prompt components.

messages · object[] · required

The messages that were processed.

Show child attributes

promptVariables · object

Template variables used or detected for this conversation.

Show child attributes

templateMatch · object

Template match info when content was auto-matched against an existing template.

Show child attributes