Submit an externally signed source event

POST

/katara/v1/orgs/{org_id}/environments/{environment_id}/event-sources/{source_id}/events

const url = 'https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/event-sources/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/events';
const options = {
  method: 'POST',
  headers: {'X-Katara-Event-Signature': 'example', 'Content-Type': 'application/json'},
  body: '{"org_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","environment_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","schema_version":1,"source_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","source_version":{"id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","version":1,"integrity":"example"},"activation_generation":1,"mode":"test","reset_generation":1,"event_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","occurred_at":"2026-04-15T12:00:00Z","input_ref":{"org_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","environment_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","version":1,"integrity":"example","media_type":"application/json","size_bytes":1},"signed_at":"2026-04-15T12:00:00Z"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/event-sources/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/events \
  --header 'Content-Type: application/json' \
  --header 'X-Katara-Event-Signature: example' \
  --data '{ "org_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "environment_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "schema_version": 1, "source_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "source_version": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": 1, "integrity": "example" }, "activation_generation": 1, "mode": "test", "reset_generation": 1, "event_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "occurred_at": "2026-04-15T12:00:00Z", "input_ref": { "org_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "environment_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": 1, "integrity": "example", "media_type": "application/json", "size_bytes": 1 }, "signed_at": "2026-04-15T12:00:00Z" }'

Server-to-server signed producer ingress. Body1–16384 raw bytes; exact application/json Content-Type. Authorization, Cookie, Origin, Idempotency-Key, Content-Encoding and query parameters are refused. Sign Ed25519 over UTF8(katara.synapse.event.v1), NUL, UTF8(enrolled signing key UUID), NUL, and ASCII(sha256: plus lowercase SHA256 hex of the exact transmitted body bytes). Send canonical padded base64 of the 64-byte signature. Keep the private key exclusively at the external source. Whole-second UTC signed_at must be newer than 5 minutes ago, at most 30 seconds in the future and no earlier than occurred_at. A fresh signature may repeat unchanged semantic event metadata, subject to current source authority. Altered semantic fields conflict with the existing receipt. Source existence, invalid signatures and revoked authority share HTTP403. A persisted receipt does not prove run execution. The portal never sends signed events.

Parameters

Path Parameters

org_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

environment_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

source_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

Header Parameters

X-Katara-Event-Signature

required

string

/^[A-Za-z0-9+/]{85}[AQgw]==$/

Request Body^required

application/json

object

org_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

environment_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

schema_version

required

Allowed value: 1

source_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

source_version

required

object

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

version

required

integer

>= 1 <= 9223372036854776000

integrity

required

string

/^sha256:[a-f0-9]{64}$/

activation_generation

required

integer

>= 1 <= 9007199254740991

mode

required

Allowed values: test live

reset_generation

required

integer

>= 1 <= 9007199254740991

event_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

occurred_at

required

string format: date-time

/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ$/

input_ref

object

org_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

environment_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

version

required

integer

>= 1 <= 9223372036854776000

integrity

required

string

/^sha256:[a-f0-9]{64}$/

media_type

required

Allowed values: text/plain text/markdown application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg text/csv application/zip

size_bytes

required

integer

<= 104857600

media_type

required

Allowed value: application/json

version

required

integer

>= 1 <= 9007199254740991

signed_at

required

string format: date-time

/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ$/

Responses

202

Persisted signed-event receipt. Admission and run execution remain separate.

application/json

object

org_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

environment_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

source_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

event_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

reset_generation

required

integer

>= 1 <= 9007199254740991

version_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

activation_generation

required

integer

>= 1 <= 9007199254740991

event

required

object

org_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

environment_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

schema_version

required

Allowed value: 1

source_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

source_version

required

object

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

version

required

integer

>= 1 <= 9223372036854776000

integrity

required

string

/^sha256:[a-f0-9]{64}$/

activation_generation

required

integer

>= 1 <= 9007199254740991

mode

required

Allowed values: test live

reset_generation

required

integer

>= 1 <= 9007199254740991

event_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

occurred_at

required

string format: date-time

/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ$/

input_ref

object

org_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

environment_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

version

required

integer

>= 1 <= 9223372036854776000

integrity

required

string

/^sha256:[a-f0-9]{64}$/

media_type

required

Allowed values: text/plain text/markdown application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg text/csv application/zip

size_bytes

required

integer

<= 104857600

media_type

required

Allowed value: application/json

version

required

integer

>= 1 <= 9007199254740991

digest

required

string

/^sha256:[a-f0-9]{64}$/

received_at

required

string format: date-time

/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{0,8}[1-9])?Z$/

Allowed value: 0001-01-01T00:00:00Z

expires_at

required

string format: date-time

/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{0,8}[1-9])?Z$/

Allowed value: 0001-01-01T00:00:00Z

state

required

Allowed values: pending admitted denied expired

run_id

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

projection_version

required

integer

>= 1 <= 9007199254740991

Example

{
  "event": {
    "schema_version": 1,
    "mode": "test",
    "input_ref": {
      "media_type": "application/json"
    }
  },
  "state": "pending"
}

Headers

Cache-Control

string

Allowed value: no-store

default

Request error

application/json

object

error

required

object

message

required

string

>= 1 characters <= 500 characters

type

required

string

>= 1 characters <= 100 characters

code

required

Stable; branch on it. Any operation can answer invalid_request, with param naming the refused field when there is one; human_session_required, when an API key, service account or workload calls an operation only a signed-in person may perform; reauthentication_required, when a person’s sign-in is too old for the operation; permission_denied; route_not_found and method_not_allowed, when no operation matches the path or method; and feature_unavailable, when the operation’s service is not enabled on this deployment.

string

>= 1 characters <= 100 characters

param

required

The request field a refusal is about, such as the agent_id or run_id query parameter; null when the refusal is not about one field.

string | null

request_id

required

string

>= 1 characters <= 100 characters

upstream_status

required

integer | null

action

Allowed values: sign_in reauthenticate request_access review fund retry reconcile refresh support

operation_id

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

snapshot_ref

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

Example

{
  "error": {
    "action": "sign_in"
  }
}

Submit an externally signed source event

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Responses

202

Example

Headers

default

Example

Request Body^required