API Reference

Package: dodil.scriptum.v1 · Service: ScriptumService

This is Scriptum’s own API surface — one gRPC service, ScriptumService, with an HTTP gateway mirroring every method. There is no OpenAI-style chat/completions endpoint anywhere in here; Scriptum exposes scripts, versions, threads, results, tools, env, and templates, and nothing else. Scripts run in the cloud as durable, resumable threads — there is no local execution path and no execution-mode switch to set. You create a thread, the platform schedules it, and you read results or stream events back.

State is server-backed: scripts, versions, drafts, threads, results, and artifacts all live on the server. The only thing you ever download directly is an artifact, via a short-lived pre-signed downloadUrl returned by ListArtifacts.

Conventions

Endpoints

• HTTP paths are all under /v1/scriptum/... (e.g. POST /v1/scriptum/scripts).
• gRPC methods are reached at dodil.scriptum.v1.ScriptumService/<Method> (e.g. dodil.scriptum.v1.ScriptumService/CreateThread).

Auth & org context

Every authenticated call carries a bearer token plus the caller’s org context:

-H "Authorization: Bearer $DODIL_TOKEN" \
-H "x-organization-name: $DODIL_ORG"

Resource-scoped methods (anything that names a {name} script — GetScript, SaveScriptDraft, CreateThread, …) resolve the org from the request context and authorize against the named resource. HealthCheck, ListTemplates, and GetTemplate are the only methods with no auth annotation in the proto — HealthCheck is the unauthenticated-ish liveness/version probe; the template catalog is public read-only. Treat everything else as requiring a valid token.

JSON encoding

• HTTP request and response bodies are pbjson camelCase: createdAtMs, inputJson, nextPageToken, scriptName.
• gRPC -d payloads use proto snake_case: created_at_ms, input_json, next_page_token, script_name.
• int64 fields serialize as JSON strings (e.g. "createdAtMs": "1748390400000").
• The JSON-payload fields — input_json, output_data, ast_json, ir_yaml, value_data, step input_data/output_data — carry your own data (or compiler output) as strings/bytes. They are not the request/response envelope; the envelope around them is still pbjson/proto as above. bytes fields (output_data, value_data, step data) are base64 over HTTP.

Version selector

Across the API, version = 0 means “the contextual default”:

• CreateThread / TestScriptDraft → the script’s active version.
• GetScriptCode → the current draft code.
• RollbackScript (target_version = 0) → the previous active version.

Pagination

List methods that page take pageSize + pageToken and return nextPageToken (empty when exhausted): ListScripts, ListTools, ListThreads, ListTemplates.

Streaming

WatchThread, WatchStep, StreamThreadResult, and StreamStepResult are server-streaming. Watch streams carry signals only (status transitions, decisions, yields) with no bulk payloads; the result streams carry chunked bytes (metadata chunk first, then ordered chunkIndex data chunks ending with isFinal: true). The unary GetThreadResult caps output at ~4MB and sets outputTruncated / step outputTruncated when you should switch to a stream.

Sections

• Scripts & Versioning — CreateScript, ListScripts, GetScript, DeleteScript, the draft lifecycle (SaveScriptDraft → CompileScriptDraft → TestScriptDraft → PublishScriptDraft), RollbackScript, ListScriptVersions, GetScriptVersion, GetScriptCode, GetDraftInfo.
• Threads & Results — CreateThread, GetThread, ListThreads, CancelThread, ResumeThread, WatchThread, WatchStep, GetThreadResult, StreamThreadResult, StreamStepResult, ListArtifacts, plus the streaming event catalog.
• Tools, Env & Templates — ListTools; tenant env (SetEnvVar, GetEnvVar, ListEnvVars, DeleteEnvVar, ImportEnvVars) and the per-script env overlay (GetScriptEnv, UpdateScriptEnv); ListTemplates, GetTemplate; HealthCheck.
• ScriptContract Appendix — the typed-I/O contract (ScriptContract, TypedField, TypeRef, EnumDef) and the service enums (ScriptStatus, ScriptVersionStatus, ThreadStatus, StepStatus).

See also

• API Reference — this hub
• Core Concepts — script, version, draft, thread, artifact
• Scriptum Language — the DSL you compile into versions