---
title: "Write events from any program into the work graph log [write]"
method: POST
path: "/events"
tags: ["Events"]
---

# Write events from any program into the work graph log \[write\]

`POST /events`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/events`
- Auth: HTTP bearer

Appends up to 500 events in the same envelope GET /events returns, from an agent running elsewhere, a script or your own app. Each event's idempotency_key is unique per log: pushing it again answers status duplicate with the existing id and writes nothing. log person (default) is your private log; workspace is your workspace's shared log. task_id or session_id must be one you can open. bodies are kept whole, whatever their size: text or base64 inline, or file_id of a file uploaded first through POST /files/uploads for large ones; credentials in text bodies are masked before storage. source.system names your program; the platform's own systems are refused (400 reserved_source). The whole batch is checked before anything is written.

## Request body

- object
  - `events` object[], required
    - `idempotency_key` string, required
    - `log` 'person' | 'workspace'
    - `kind` string, required: Dotted lowercase type, e.g. tool.call, slack.message
    - `occurred_at` string, date-time
    - `clock_source` 'device' | 'platform'
    - `actor` object
      - `kind` 'person' | 'agent' | 'teammate' | 'guest' | 'external' | 'system'
      - `platform_user` object
      - `label` string
    - `surface` string
    - `source` object, required
      - `system` string, required
      - `kind` string, required
      - `version` string
    - `objects` object[]
      - `type` string, required
      - `id` string, required
      - `role` string
    - `payload` object
    - `correlation` object
    - `task_id` string
    - `session_id` string
    - `bodies` object[]
      - `role` string
      - `media_type` string
      - `text` string
      - `base64` string
      - `file_id` string
      - `complete` boolean

## Response `200`

One result per event, in order

- object
  - `data` object[]
    - `idempotency_key` string
    - `status` 'created' | 'duplicate'
    - `id` string

## Other responses

- `400`: Invalid filter, time or cursor
- `401`: Authentication required
- `404`: Unknown, not visible to the caller, or the work graph is off for this workspace
- `503`: The work graph is not migrated yet
- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/events/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/0d435187cd55?raw)