Minimal events

Public event streams and inbound hooks.

This page is generated from the Minimal route table. Every operation carries the permission it needs and the anchor an agent can link to.

GET /api/v1/events/{token}

GETNo permission neededpublic faceServer sent eventsToken in the path

Source: internal/api/events.go:mountEvents handleEventStream

Stream widget events

Streams widget events as server sent events. The token in the path is the only credential, so treat the whole URL as a secret.

Parameters

Name	In	Type	Required	Description
token	path	string	Yes	The stream token issued with the subscription.

Responses

Status	Body	Description
200	text/event-stream, string	An open event stream.
404	application/problem+json, Problem	The request was refused. The body says why.

Request samples

curl

# This operation is public. It takes no credentials.
# This endpoint streams server sent events. The response stays open.
curl -X GET 'https://depot.example.com/api/v1/events/<token>' \
  -H 'Accept: application/json'

PowerShell

# This operation is public. It takes no credentials.
# This endpoint streams server sent events. The response stays open.

$headers = @{
    'Accept' = 'application/json'
}

$response = Invoke-RestMethod `
    -Method Get `
    -Uri 'https://depot.example.com/api/v1/events/<token>' `
    -Headers $headers

$response | ConvertTo-Json -Depth 10

Python

# This operation is public. It takes no credentials.
# This endpoint streams server sent events. The response stays open.

import requests

url = "https://depot.example.com/api/v1/events/<token>"
headers = {
    "Accept": "application/json",
}

response = requests.get(url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

Go

// This operation is public. It takes no credentials.
// This endpoint streams server sent events. The response stays open.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
)

func main() {
  req, err := http.NewRequest(http.MethodGet, "https://depot.example.com/api/v1/events/<token>", nil)
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Set("Accept", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()

  out, err := io.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(resp.Status, string(out))
}

TypeScript

// This operation is public. It takes no credentials.
// This endpoint streams server sent events. The response stays open.

const url = "https://depot.example.com/api/v1/events/<token>";

const response = await fetch(url, {
  method: "GET",
  headers: {
    "Accept": "application/json",
  },
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

C#

// This operation is public. It takes no credentials.
// This endpoint streams server sent events. The response stays open.

using System;
using System.Net.Http;

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://depot.example.com/api/v1/events/<token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

POST /api/v1/events/hooks/{token}

POSTNo permission neededpublic faceInbound hookToken in the path

Source: internal/api/events.go:mountEvents handleEventHook

Receive an inbound hook

Accepts an event from an outside system. The token in the path authenticates the caller.

Parameters

Name	In	Type	Required	Description
token	path	string	Yes	The hook token issued when the integration was configured.

Request body

Required, sent as application/json.

Field	Type	Description
kindrequired	string, one of created, updated, retired	What happened.
occurredAtrequired	string (date-time)	When it happened, in UTC.
widgetId	string (uuid)	Which widget it happened to.
payload	object	Whatever the sender attached.

Responses

Status	Body	Description
202	None	The event was accepted.
400	application/problem+json, Problem	The request was refused. The body says why.

Request samples

curl

# This operation is public. It takes no credentials.
curl -X POST 'https://depot.example.com/api/v1/events/hooks/<token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{
  "kind": "created",
  "occurredAt": "2026-01-01T00:00:00Z",
  "widgetId": "00000000-0000-0000-0000-000000000000",
  "payload": {}
}'

PowerShell

# This operation is public. It takes no credentials.

$headers = @{
    'Accept' = 'application/json'
    'Content-Type' = 'application/json'
}

$body = @'
{
  "kind": "created",
  "occurredAt": "2026-01-01T00:00:00Z",
  "widgetId": "00000000-0000-0000-0000-000000000000",
  "payload": {}
}
'@

$response = Invoke-RestMethod `
    -Method Post `
    -Uri 'https://depot.example.com/api/v1/events/hooks/<token>' `
    -Headers $headers `
    -ContentType 'application/json' `
    -Body $body

$response | ConvertTo-Json -Depth 10

Python

# This operation is public. It takes no credentials.

import requests

url = "https://depot.example.com/api/v1/events/hooks/<token>"
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
}
payload = {
    "kind": "created",
    "occurredAt": "2026-01-01T00:00:00Z",
    "widgetId": "00000000-0000-0000-0000-000000000000",
    "payload": {},
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
print(response.json())

Go

// This operation is public. It takes no credentials.
package main

import (
  "bytes"
  "fmt"
  "io"
  "log"
  "net/http"
)

func main() {
  body := []byte(`{
  "kind": "created",
  "occurredAt": "2026-01-01T00:00:00Z",
  "widgetId": "00000000-0000-0000-0000-000000000000",
  "payload": {}
}`)

  req, err := http.NewRequest(http.MethodPost, "https://depot.example.com/api/v1/events/hooks/<token>", bytes.NewReader(body))
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Set("Accept", "application/json")
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()

  out, err := io.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(resp.Status, string(out))
}

TypeScript

// This operation is public. It takes no credentials.

const url = "https://depot.example.com/api/v1/events/hooks/<token>";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "kind": "created",
    "occurredAt": "2026-01-01T00:00:00Z",
    "widgetId": "00000000-0000-0000-0000-000000000000",
    "payload": {}
  }),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

C#

// This operation is public. It takes no credentials.

using System;
using System.Net.Http;
using System.Text;

using var client = new HttpClient();

const string body = """
{
  "kind": "created",
  "occurredAt": "2026-01-01T00:00:00Z",
  "widgetId": "00000000-0000-0000-0000-000000000000",
  "payload": {}
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://depot.example.com/api/v1/events/hooks/<token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Content = new StringContent(body, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());