publishEventSource

POST

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

const url = 'https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/event-sources';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'example',
    'X-Katara-CSRF': '1',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"source_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","expected_revision":1,"expected_environment_epoch":1,"expected_reset_generation":1,"configuration":{"name":"example","run":"example","signing_key":{"id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","public_key":"example"},"input_mode":"fixed","max_event_age_seconds":1,"max_pending_events":1}}'
};

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 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --header 'X-Katara-CSRF: 1' \
  --data '{ "source_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "expected_revision": 1, "expected_environment_epoch": 1, "expected_reset_generation": 1, "configuration": { "name": "example", "run": "example", "signing_key": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "public_key": "example" }, "input_mode": "fixed", "max_event_age_seconds": 1, "max_pending_events": 1 } }'

Requires current synapse:event_sources:write authority in the exact environment. Publication pins only a public Ed25519 signing key, event age and capacity bounds, input mode, and the complete run configuration. It neither activates nor starts a run. Activation and retirement require human sessions; enabling also requires an available event admission worker. Preserve exact request and key after an unknown mutation. No automatic retry. Fixed mode refuses event input overrides; event_reference requires an exact current approved JSON content reference, never a raw event body. Replies expose execution_ready; false refuses enabling. Test and Live authority, reset and funding remain separate. Signing private keys must stay with the external source. This metadata API does not expose event admission receipts.

Authorizations

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

Header Parameters

Idempotency-Key

required

string

/^[A-Za-z0-9._:-]{8,128}$/

X-Katara-CSRF

Allowed value: 1

Browser cookie mutations require value 1 and an allowed Origin. Session bearer clients may omit this header.

X-Katara-Account-ID

string format: uuid

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

Required for cookie-authenticated changes. Use the UUID of the account that loaded the application. A different current cookie account returns account_changed before the handler runs. Session bearer and API key clients do not require this header.

Request Body^required

application/json

object

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

expected_revision

required

integer

<= 9007199254740990

expected_environment_epoch

required

integer

>= 1 <= 9007199254740991

expected_reset_generation

required

integer

>= 1 <= 9007199254740991

configuration

required

object

name

required

string

>= 1 characters <= 120 characters

run

required

Model, tools, schemas and limits come from the immutable agent version. Paid Test Compute requires the exact consent funding the grant budget; the API checks it against current payer authority.

object

agent_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 <= 9007199254740991

integrity

required

string

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

grant_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

input_ref

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

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 <= 9007199254740991

integrity

required

string

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

media_type

required

Allowed value: application/json

size_bytes

required

integer

<= 1048576

budget_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

usage_class

required

Allowed values: simulation test_compute live

paid_test_consent_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

output_target

required

Explicit destination for run artifacts. Store and key versions must still be active at admission and byte access. Choose retention from 60 seconds to 365 days; no silent default or destination substitution.

object

store_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

store_version

required

integer

>= 1 <= 9007199254740991

key_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

key_version

required

integer

>= 1 <= 9007199254740991

retention_seconds

required

integer

>= 60 <= 31536000

workload_grants

required

Array<object>

>= 1 items <= 8 items unique items

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

audience

required

Allowed values: katara:synapse katara:locus

signing_key

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

public_key

required

Canonical base64 of the 32-byte Ed25519 public key. Never send a private signing key.

string

/^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$/

input_mode

required

Allowed values: fixed event_reference

max_event_age_seconds

required

integer

>= 10 <= 86400

max_pending_events

required

integer

>= 1 <= 10000

Responses

201

Event-source metadata or completed immutable operation; no execution implied.

application/json

object

operation_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

resource_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

completed

required

boolean

Example^generated

{
  "operation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "resource_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "completed": true
}

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"
  }
}

publishEventSource

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Responses

201

Examplegenerated

Headers

default

Example

Request Body^required

Example^generated