Conventions

The baseline for every Scriptum API call.

Transport and endpoints

Scriptum is reachable over gRPC (what the dodil scriptum CLI uses) and over HTTP/JSON (pbjson transcoding). There’s a single service, dodil.scriptum.v1.ScriptumService.

HTTP paths live under /v1/scriptum/.... Examples in these docs use staging.

Auth

Send a bearer token on every authenticated call:

• Authorization: Bearer <token>

Your organization context travels with the token — the gateway derives it, so you don’t pass an org id yourself. A couple of read-only operations (HealthCheck, template reads) need no auth.

Get a token with dodil login (interactive), or programmatically — apps and agents use the OAuth client-credentials flow. See Get an Access Token .

Wire format

• HTTP field names are camelCase (pbjson); gRPC request bodies use the proto’s snake_case names.
• int64 values are encoded as JSON strings.
• Fields like inputJson, outputData, astJson, and irYaml carry your data (JSON strings or bytes) — that’s your payload, not the API envelope.

Streaming

Several RPCs stream (server-streaming, over both gRPC and HTTP): WatchThread, WatchStep, StreamThreadResult, StreamStepResult. Use them to follow a thread live and to pull large results in chunks.

Using gRPC

Every method is at dodil.scriptum.v1.ScriptumService/<Method>. With grpcurl:

export SCRIPTUM_GRPC="rpc.dev.dodil.io:443"   # staging; production: rpc.dodil.io:443
grpcurl -H "Authorization: Bearer $DODIL_TOKEN" $SCRIPTUM_GRPC list

gRPC request bodies use proto snake_case; grpcurl renders responses in camelCase.

See also

• API Reference · CLI Guide · Auth and Access