Config, Tools, Templates, and Health API

Last validated: 2026-05-14

This page covers tenant configuration APIs, script env overlays, tool catalog APIs, template discovery, and service health checks.

1) Tenant Env APIs

RPC	HTTP annotation	Status	Use case
`SetEnvVar`	`PUT /v1/scriptum/env`	Implemented	Upsert one tenant env key
`GetEnvVar`	`GET /v1/scriptum/env/{key}`	Implemented	Read one key
`ListEnvVars`	`GET /v1/scriptum/env`	Partial	List all env entries
`DeleteEnvVar`	`DELETE /v1/scriptum/env/{key}`	Implemented	Remove key
`ImportEnvVars`	`POST /v1/scriptum/env/import`	Implemented	Bulk import/overwrite

Argument details

SetEnvVarRequest.key, value: both required.
ImportEnvVarsRequest.vars{}: map of key-value pairs, overwritten on conflict.

Current caveat:

ListEnvVars returns keys and values (not keys-only). Treat as sensitive output.

2) Script Env Overlay APIs

RPC	HTTP annotation	Status	Use case
`GetScriptEnv`	`GET /v1/scriptum/scripts/{name}/env`	Implemented	Read per-script overlay
`UpdateScriptEnv`	`PATCH /v1/scriptum/scripts/{name}/env`	Implemented	Upsert/delete overlay keys

Merge semantics

Effective env at run time is:

tenant base env
overlaid by script env
with empty-defers behavior for empty script values

UpdateScriptEnvRequest fields:

name: script name
set{}: keys to upsert
delete[]: keys to remove

Conflict rule:

If the same key is present in both set and delete, delete wins in resulting overlay.

3) Tool APIs

RPC	HTTP annotation	Status	Use case
`RegisterTool`	`POST /v1/scriptum/tools`	Unimplemented	Register custom tool
`ListTools`	`GET /v1/scriptum/tools`	Partial	Enumerate available tools
`GetTool`	`GET /v1/scriptum/tools/{tool_id}`	Unimplemented	Fetch one tool definition

ListToolsRequest fields:

page_size
page_token

Current caveat:

Page token progression is limited in current runtime behavior.

4) Template APIs

RPC	HTTP annotation	Status	Use case
`ListTemplates`	`GET /v1/scriptum/templates`	Implemented	Discover starter templates
`GetTemplate`	`GET /v1/scriptum/templates/{id}`	Implemented	Retrieve template details + DSL

ListTemplatesRequest fields:

tags[], labels[]
category
search
page_size, page_token

Use cases:

Catalog explorer in UI.
Script bootstrap pipelines (CreateScript.from_template).

5) Health API

RPC	HTTP annotation	Status	Use case
`HealthCheck`	`GET /v1/scriptum/health`	Implemented	Programmatic service-level health/version check

Response fields:

status
version
uptime_seconds

Also available as direct management HTTP endpoints:

GET /health
GET /ready
GET /metrics

6) Example Calls

gRPC env import + script overlay update


# Import tenant env
grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"vars":{"OPENAI_API_KEY":"...","DB_HOST":"db.internal"}}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/ImportEnvVars
 
# Apply script overlay
grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"name":"invoice-parser","set":{"MODEL":"gpt-4.1"},"delete":["LEGACY_FLAG"]}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/UpdateScriptEnv

gRPC template discovery


grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"category":"extraction","search":"invoice","page_size":20}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/ListTemplates

HTTP management probes


curl -sS "https://api.dev.dodil.io:443/health"
curl -sS "https://api.dev.dodil.io:443/ready"

7) Client Recommendations

Avoid printing env listings in shared logs.
Keep script overlays minimal and explicit to reduce configuration drift.
Cache template lists in UI clients, but always fetch template content by ID before bootstrap.
Treat UNIMPLEMENTED tool APIs as expected until server support is added.