Record an activity

Use Actera’s activity operation to report an AI agent action observed by your integration. It supports traffic discovery and can link to a decision, but it is not authorization, managed execution, or proof an external operation succeeded.

POST/v1/activities

Parameters

Parameter	Location	Required	Description
Actera-Workspace-Id	Header	Yes	Workspace UUID selected by the authenticated principal.

Request fields

Field	Required	Description
activity.idempotency_key	Yes	Stable key for this reported occurrence.
activity.event_type	Yes	Integration-defined event classification.
activity.agent.id	Yes	Agent that performed or attempted the action.
activity.action.type	Yes	Stable operation name.
activity.action.attributes	No	Observed action values.
activity.context	No	Additional observed facts.
activity.occurred_at	No	Occurrence time; receipt time is used when omitted.
activity.decision_id	No	Related decision. Agent and action must match.
activity.details	No	Additional reporting metadata.

Request

curl --request POST "$ACTERA_BASE_URL/v1/activities" \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $ACTERA_ACCESS_TOKEN" \
  --header "Actera-Workspace-Id: $ACTERA_WORKSPACE_ID" \
  --data '{
    "activity": {
      "idempotency_key": "activity-refund-01842",
      "event_type": "tool.completed",
      "agent": { "id": "refund-agent" },
      "action": { "type": "refund.create", "attributes": { "customer_id": "cus_123" } },
      "decision_id": "dec_7f26",
      "details": { "provider_receipt": "re_918" }
    }
  }'

Response

Success returns 201 Created and the activity directly.

{
  "id": "act_52aa",
  "idempotency_key": "activity-refund-01842",
  "event_type": "tool.completed",
  "decision_id": "dec_7f26",
  "recorded_at": "2026-09-05T10:20:01Z"
}

Missing fields return 400. A missing linked decision returns 404; mismatched agent or action evidence returns 409. Exact retries return the recorded activity, while changed input under the same key returns 409. See Start from observed traffic for the policy workflow and API conventions for shared retry guidance.