Events API

Ariftly uses an event-sourced architecture. Every state change in the platform is recorded as an immutable event. The Events API lets you stream and query the event log.

Event types

Event Type	Emitted When
task.created	A task is dispatched
task.progress	An agent emits a progress update
task.complete	An agent completes a task
task.failed	An agent reports failure
artifact.emitted	An agent emits an artifact
approval.requested	An agent requests human approval
approval.resolved	A human approves or denies
session.message	A message is added to a session
session.closed	A session ends
tool_call.executed	The tool proxy executes a tool call

Stream events (SSE)

GET /events/stream

Returns a Server-Sent Events stream of all events in real time.

Query parameters:

Parameter	Description
task_id	Only stream events for a specific task
agent	Only stream events from a specific agent
types	Comma-separated list of event types to include

Example:

curl -N https://api.ariftly.io/v1/events/stream \
  -H "Authorization: Bearer $ARIFTLY_API_KEY" \
  -H "Accept: text/event-stream" \
  --data-urlencode "task_id=task_01j9x8k..."

SSE stream format:

event: task.progress
data: {"task_id":"task_01j9x8k...","message":"Analyzing document","progress":0.3}

event: artifact.emitted
data: {"task_id":"task_01j9x8k...","artifact_id":"art_01j9x8m...","type":"ai_readiness.questionnaire_response"}

event: task.complete
data: {"task_id":"task_01j9x8k...","artifact_count":1}

List events

GET /events

Query historical events.

Query parameters:

Parameter	Type	Description
task_id	string	Filter by task
agent	string	Filter by agent
type	string	Filter by event type
after	ISO 8601	Events after this timestamp
before	ISO 8601	Events before this timestamp
limit	integer	Max results. Default: 50, max: 500

Webhooks

Subscribe to events via webhook instead of polling:

POST /webhooks

{
  "url": "https://your-server.com/ariftly-webhook",
  "events": ["task.complete", "approval.requested"],
  "secret": "your-signing-secret"
}

Webhook payloads are signed with HMAC-SHA256. Verify the X-Ariftly-Signature header:

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}