Log Interaction

POST/v1/core/interactions/log

Logs a behavioral interaction that an agent took on an entity. This builds the behavioral graph used for future ML recommendations.

Request

{
  "entity_id": "ent_550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "outreach-agent-v1",
  "api": "sendgrid",
  "action_type": "send_email",
  "action": "sent follow-up reminder email",
  "outcome": "success",
  "metadata": {
    "template_id": "tpl_123"
  }
}

Parameters

Name	Type	Required	Description
entity_id	string	Yes	Target entity UUID
agent_id	string	Yes	Name/ID of the agent acting
api	string	Yes	External service used (stripe, github, etc)
action_type	string	Yes	High level action category (send_email)
action	string	Yes	Description of what happened
outcome	string	Yes	success, failed, pending, ignored, unknown
intent	string	No	Goal of the action (e.g. payment_recovery)
metadata	object	No	Custom JSON data

Response

Returns the ID of the created interaction log.

{
  "interaction_id": "int_3A21F...",
  "entity_id": "ent_550e...",
  "logged_at": "2026-03-04T12:00:00Z"
}

---

Batch Log Interactions

POST/v1/core/interactions/batch

You can log up to 100 interactions in a single request for high-volume agents.

Request

{
  "interactions": [
    {
      "entity_id": "...",
      "api": "...",
      "action_type": "...",
      "action": "...",
      "outcome": "...",
      "agent_id": "..."
    }
  ]
}