Invoke an operation a registered extension exposes

curl --request POST \
  --url https://api.example.com/v1/extensions/{name}/invoke \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "operation": "start-review",
  "payload": {
    "sessionId": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d"
  }
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/extensions/{name}/invoke"

	payload := strings.NewReader("{\n  \"operation\": \"start-review\",\n  \"payload\": {\n    \"sessionId\": \"6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    operation: 'start-review',
    payload: {sessionId: '6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d'}
  })
};

fetch('https://api.example.com/v1/extensions/{name}/invoke', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/extensions/{name}/invoke"

payload = {
    "operation": "start-review",
    "payload": { "sessionId": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "payload": {
    "accepted": true
  }
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

Invoke an operation a registered extension exposes

The generic request lane for extension-defined behaviour, and the near half of the registered extension’s own invoke operation: a client reaches an extension THROUGH this host, needing nothing but the extension’s name and never holding its secret. The host signs the forwarded call under the registration’s secret, judges the address on the way out and refuses a redirect; the payload is the extension’s own contract and the host only routes it.

The address is configuration, not a credential. listExtensions shows endpoint to every member of the organisation on purpose — a registry that hid where an extension points would answer “what is reading our conversations” with less than the truth — so what this lane withholds is the secret and the signature, not the URL. Knowing the address buys nothing without the secret: every call in the extension contract is signed, and an extension is required to refuse anything that does not verify.

An ordinary member’s token is enough. Invoking is using, and only registering is owning — extensions:manage gates the writes that create, re-point, revoke and re-order a registration.

The forward runs under the same deadline a transformation gets.

POST

extensions

{name}

invoke

Invoke an operation a registered extension exposes

curl --request POST \
  --url https://api.example.com/v1/extensions/{name}/invoke \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "operation": "start-review",
  "payload": {
    "sessionId": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d"
  }
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/extensions/{name}/invoke"

	payload := strings.NewReader("{\n  \"operation\": \"start-review\",\n  \"payload\": {\n    \"sessionId\": \"6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    operation: 'start-review',
    payload: {sessionId: '6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d'}
  })
};

fetch('https://api.example.com/v1/extensions/{name}/invoke', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/extensions/{name}/invoke"

payload = {
    "operation": "start-review",
    "payload": { "sessionId": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "payload": {
    "accepted": true
  }
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

Authorizations

Authorization

string

header

required

Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.

Path Parameters

name

string

required

The extension's namespaced name, publisher/extension form.

Pattern: ^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$

Example:

"lerian/ring-review"

Body

application/json

A request to run one operation a host extension exposes.

operation

string

required

The operation name, as listed on the extension.

Maximum string length: 128

payload

object

Free-form input — the extension's own contract.

Response

The operation's result, as the extension defined it.

payload

object

Free-form output — the extension's own contract.

Overview

Host

Sessions

Messages

Events

Lanes

Monitors

Agents

Skills and commands

Permissions

Peers

Packages

Extensions

Workflows

Schedules

Providers

Records

Environments

Sharing

Refinements

Platform

Error handling

Invoke an operation a registered extension exposes

Authorizations

Path Parameters

Body

Response