Endpoint Execution Scopes

When writing Custom Endpoints, your code executes within a specific scope that determines what operations are allowed.

Reading the request body

Body is the request stream, not a string, so a payload is parsed straight off it instead of being turned into text first:

public record AssignRequest(UID128 CaseUID, UID128 AssigneeUID);

var req = ParseBody<AssignRequest>();

• ParseBody<T>() reads the body as JSON. An empty body gives back the default value. The stream is rewound for you, so it can be called more than once.
• ParseBody<UID128>() is the exception: it reads a bare, optionally JSON-quoted UID rather than JSON — the endpoint shape whose whole payload is a node identifier.
• ReadBodyAsText() reads the whole body as text, for a payload that is not JSON. It returns an empty string when there is no body.

Endpoints Scope

This is the standard scope for endpoints running on a Primary node or when the system allows write access.

Class: CodeEndpointExecutionScope

Read-Only Endpoints Scope

This scope is used when an endpoint is executed on a Read-Only Replica, or when the endpoint itself is marked ReadOnly (the [endpoint: Curiosity.Endpoints.ReadOnly] attribute on export). You cannot modify the graph directly in this scope. However, you can use RunEndpointOnPrimaryAsync to forward write operations to the primary node.

Class: ReadOnlyCodeEndpointExecutionScope

RunEndpointAsync<T> — calling another endpoint in-process

RunEndpointAsync invokes another endpoint inside the same workspace process — no HTTP, no loopback. The target endpoint's Code is compiled (or fetched from the compile cache) and its scope is constructed with the body, headers, user, and admin status you pass in.

Full signature:

Task<T> RunEndpointAsync<T>(
    EndpointUID endpointName,
    string body = null,
    UID128? user = null,
    bool? runAsAdmin = null,
    bool propagateStatus = true,
    IReadOnlyDictionary<string, StringValues> headers = null,
    CancellationToken cancellationToken = default
) where T : class;

Behavior:

T is deserialized from the response body. Use string to receive the raw payload; use a record/POCO to JSON-deserialize.

// Identity preserved — the called endpoint sees CurrentUser, same admin status.
var summary = await RunEndpointAsync<CaseSummary>(
    Endpoints.Cases.Summarize,   // endpoint at path "cases/summarize"
    $"{{\"caseId\":\"{caseId}\"}}");

// Run as a different user (e.g. the case owner) with a fresh admin state.
var report = await RunEndpointAsync<string>(
    Endpoints.Cases.ExportPdf,   // endpoint at path "cases/export-pdf"
    body: null, user: caseOwnerUID, runAsAdmin: false);

RunEndpointOnPrimaryAsync<T> — from a read-only replica

In a primary / read-only replica deployment, replicas serve reads from the same shared storage as the primary but cannot write. RunEndpointOnPrimaryAsync is the escape hatch when a read-only endpoint needs to perform writes — it forwards the call to the primary so the work happens there.

Full signature (on the writable scope):

Task<T> RunEndpointOnPrimaryAsync<T>(
    EndpointUID endpointName,
    string body = null,
    UID128? user = null,
    bool? runAsAdmin = null,
    bool propagateStatus = true,
    CancellationToken cancellationToken = default
) where T : class;

How it behaves depends on which node you're on:

Flow from a replica

The replica polls every second while the primary returns 202 Accepted (used by pooling endpoints). The CalculationProgress header, when present, is forwarded through RelayStatusAsync so the original caller sees the same status messages they would see if the work had run locally.

Identity propagation

The user UID travels in the X-MSK-User header. On the primary, CurrentUser resolves to that UID, and ACL filtering applies as usual. If CurrentUser was default on the replica (token call), it stays default on the primary.

Typical pattern

public record AddNoteRequest(string CaseId, string Note);

if (Graph.Internals.ReadOnly)
{
    return await RunEndpointOnPrimaryAsync<string>(Endpoints.Cases.AddNote, Body); // endpoint at path "cases/add-note"
}

// Running on the primary — do the write locally.
var req = ParseBody<AddNoteRequest>();
var node = await Graph.GetOrAddLockedAsync(N.SupportCase.Type, req.CaseId);
node.Set(N.SupportCase.Notes, req.Note);
await Graph.CommitAsync(node);
return "ok";

For the full replica configuration (storage requirements, env vars), see Read-Only Replicas.

RunToolAsync — invoking an AI tool

Task<ToolCallResult> RunToolAsync<T>(
    UID128 toolUID,
    string functionName,
    string argumentsJson = null,
    UID128? user = null,
    UID128 chatTaskUID = default,
    CancellationToken cancellationToken = default
) where T : class;

The generic T is currently unused; the return is always ToolCallResult, whose Result property holds the tool's string output. Tools always run as the supplied (or current) user with ACL enforcement — there is no admin override here.

var result = await RunToolAsync<string>(
    AI_Tools.SearchKnowledgeBase,
    functionName: "search",
    argumentsJson: $"{{\"query\":\"laptop overheating\",\"top_k\":5}}");

return Ok(result.Result);

Use the auto-generated AI_Tools.* constants from Auto-generated Helpers instead of hard-coding UIDs.

Sharing code between endpoints and AI tools

To call helper methods defined in another endpoint or share types across endpoints and AI tools, use the //ImportEndpoint("path") directive — see Importing Endpoint Code.

For more on Replicas, see Read-Only Replicas.