Tools, Env & Templates — API Reference

Package: dodil.scriptum.v1 · Service: ScriptumService

This page covers the supporting surface: tools (the callable units a script’s execute steps bind to), environment variables (tenant-wide config plus a per-script overlay), public templates, and the health probe.

gRPC reaches every method at dodil.scriptum.v1.ScriptumService/<Method>; the HTTP gateway mirrors each one under /v1/scriptum. HTTP bodies are pbjson (camelCase); gRPC -d uses proto snake_case; int64 fields are JSON strings. ListTemplates, GetTemplate, and HealthCheck carry no auth annotation (public read-only / liveness); everything else requires a bearer token + org context.

RPC	HTTP
`ListTools`	`GET /v1/scriptum/tools`
`SetEnvVar`	`PUT /v1/scriptum/env`
`GetEnvVar`	`GET /v1/scriptum/env/{key}`
`ListEnvVars`	`GET /v1/scriptum/env`
`DeleteEnvVar`	`DELETE /v1/scriptum/env/{key}`
`ImportEnvVars`	`POST /v1/scriptum/env/import`
`GetScriptEnv`	`GET /v1/scriptum/scripts/{name}/env`
`UpdateScriptEnv`	`PATCH /v1/scriptum/scripts/{name}/env`
`ListTemplates`	`GET /v1/scriptum/templates`
`GetTemplate`	`GET /v1/scriptum/templates/{id}`
`HealthCheck`	`GET /v1/scriptum/health`

Tools

A tool is a callable unit (defined by a tool.yaml) that a script’s execute steps invoke. Tools come from the built-in native set and Ignite (Dodil Cloud); scripts reference them by name (surfaced in tools_required). The API surface here is read-only — ListTools.

`ListTools`

Cursor-paginated list of tools available to the tenant.

Request

Field	Type	Notes
`page_size`	`int32`	Max tools per page.
`page_token`	`string`	Token from a previous response.

HTTP


curl -sS "https://api.dev.dodil.io/v1/scriptum/tools?pageSize=20" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG"

Response

ListToolsResponse { repeated Tool tools = 1; string next_page_token = 2; } — each is a Tool.

The `Tool` type

Field	Type	Notes
`tool_id`	`string`
`name`	`string`
`version`	`string`
`description`	`string`
`inputs`	`repeated ToolParam`	`{ name, type, required, default_value, description }`.
`outputs`	`repeated ToolParam`	Same shape as inputs.
`runtime`	`ToolRuntime`	`entrypoint`, `language`, `image`, `timeout`, `memory`, `gpu`.
`created_at_ms`	`int64`

Environment variables

Scriptum env has two layers:

Tenant env — org-wide key/value config managed by SetEnvVar / GetEnvVar / ListEnvVars / DeleteEnvVar / ImportEnvVars.
Per-script overlay — a script-scoped map managed by GetScriptEnv / UpdateScriptEnv (and seeded via CreateScript.env).

At thread start (when load_env is set), the overlay is merged on top of the tenant env using empty-defers semantics: a script value wins on a key collision only when it is non-empty; an empty or absent overlay value defers to the tenant value. This lets a script pin overrides while still inheriting most config from the tenant.

`SetEnvVar`

Creates or updates one tenant variable.

Request

Field	Type	Notes
`key`	`string`	Required. Variable key.
`value`	`string`	Required. Variable value.

HTTP


curl -sS -X PUT "https://api.dev.dodil.io/v1/scriptum/env" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -H "Content-Type: application/json" \
  -d '{ "key": "API_KEY", "value": "sk-abc123..." }'

Response

SetEnvVarResponse { string key = 1; }.

`GetEnvVar`

Request

Field	Type	Notes
`key`	`string`	Required. Variable key to retrieve.

HTTP


curl -sS "https://api.dev.dodil.io/v1/scriptum/env/API_KEY" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG"

Response

GetEnvVarResponse { string key = 1; string value = 2; }.

`ListEnvVars`

Lists all tenant env entries.

Request

No fields (ListEnvVarsRequest {}).

HTTP


curl -sS "https://api.dev.dodil.io/v1/scriptum/env" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG"

Response

ListEnvVarsResponse { repeated EnvVarEntry vars = 1; } where EnvVarEntry { string key = 1; string value = 2; }.

`DeleteEnvVar`

Request

Field	Type	Notes
`key`	`string`	Required. Variable key to delete.

HTTP


curl -sS -X DELETE "https://api.dev.dodil.io/v1/scriptum/env/API_KEY" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG"

Response

Empty (DeleteEnvVarResponse {}).

`ImportEnvVars`

Bulk import: existing keys are overwritten, new keys added.

Request

Field	Type	Notes
`vars`	`map<string, string>`	Required. Key/value pairs to import.

HTTP


curl -sS -X POST "https://api.dev.dodil.io/v1/scriptum/env/import" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -H "Content-Type: application/json" \
  -d '{ "vars": { "API_KEY": "sk-abc", "REGION": "us-east-1" } }'

Response

ImportEnvVarsResponse { int32 count = 1; } — number of variables imported.

`GetScriptEnv`

Returns the per-script env overlay for a script (the keys layered on top of tenant env). Empty when no overlay has been configured. Entries are sorted by key ascending.

Request

Field	Type	Notes
`name`	`string`	Required. Script whose overlay to fetch.

HTTP


curl -sS "https://api.dev.dodil.io/v1/scriptum/scripts/ap-pay-cycle/env" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG"

Response

GetScriptEnvResponse { repeated EnvVarEntry vars = 1; } — the overlay entries, sorted by key.

`UpdateScriptEnv`

Updates the per-script overlay. set upserts the given keys (a merge — keys not in set are untouched); delete removes the listed keys (absent keys ignored). Returns the resulting full overlay.

An empty value in set is preserved deliberately: it triggers the engine’s empty-defers rule, so the tenant value passes through for that key at thread start.

Request

Field	Type	Notes
`name`	`string`	Required. Script whose overlay to update.
`set`	`map<string, string>`	Keys to upsert (merge). Empty value → defers to tenant.
`delete`	`repeated string`	Keys to remove from the overlay.

HTTP


curl -sS -X PATCH "https://api.dev.dodil.io/v1/scriptum/scripts/ap-pay-cycle/env" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "set": { "BATCH_SIZE": "500" },
    "delete": ["LEGACY_FLAG"]
  }'

Response

UpdateScriptEnvResponse { repeated EnvVarEntry vars = 1; } — the resulting overlay after applying set and delete, sorted by key.

Templates

Templates are public, read-only pre-built scripts. Use from_template on CreateScript to bootstrap a script from one. These two methods carry no auth annotation.

`ListTemplates`

Cursor-paginated, filterable by tags, labels, category, and free-text search.

Request

Field	Type	Notes
`tags`	`repeated string`	Match any of the given tags.
`labels`	`repeated LabelEntry`	Any matching key+value pair passes.
`category`	`string`	Filter by category folder, e.g. `defense`, `extraction`, `embedding`.
`page_size`	`int32`	Default 50, max 200.
`page_token`	`string`	Token from a previous response.
`search`	`string`	Free-text across name, description, tags.

HTTP


curl -sS "https://api.dev.dodil.io/v1/scriptum/templates?category=extraction&search=invoice" \
  -H "Authorization: Bearer $DODIL_TOKEN"

Response

HTTP


{
  "templates": [
    {
      "id": "invoice_parsing",
      "name": "Invoice Parsing",
      "description": "Extract structured fields from invoice PDFs",
      "tags": ["extraction"],
      "toolsRequired": ["pdf_extract"],
      "category": "extraction",
      "contract": { "inputs": [], "outputs": [] }
    }
  ],
  "nextPageToken": "",
  "totalCount": 1
}

`GetTemplate`

Returns the template info plus its raw dsl_content (read-only .scriptum source).

Request

Field	Type	Notes
`id`	`string`	Required. Template ID, e.g. `invoice_parsing`.

HTTP


curl -sS "https://api.dev.dodil.io/v1/scriptum/templates/invoice_parsing" \
  -H "Authorization: Bearer $DODIL_TOKEN"

Response

GetTemplateResponse { TemplateInfo info = 1; string dsl_content = 2; }.

`HealthCheck`

Liveness + version probe. The only method with no auth annotation beyond the public template catalog — no token required.

Request

No fields (HealthCheckRequest {}).

HTTP


curl -sS "https://api.dev.dodil.io/v1/scriptum/health"

Response

HTTP


{
  "status": "ok",
  "version": "1.4.2",
  "uptimeSeconds": "36045"
}

Tools, Env & Templates — API Reference

Tools

ListTools

Request

HTTP

gRPC

Response

The Tool type

Environment variables

SetEnvVar

Request

HTTP

gRPC

Response

GetEnvVar

Request

HTTP

gRPC

Response

ListEnvVars

Request

HTTP

gRPC

Response

DeleteEnvVar

Request

HTTP

gRPC

Response

ImportEnvVars

Request

HTTP

gRPC

Response

GetScriptEnv

Request

HTTP

gRPC

Response

UpdateScriptEnv

Request

HTTP

gRPC

Response

Templates

ListTemplates

Request

HTTP

gRPC

Response

HTTP

gRPC

GetTemplate

Request

HTTP

gRPC

Response

HealthCheck

Request

HTTP

gRPC

Response

HTTP

gRPC

See also

`ListTools`

The `Tool` type

`SetEnvVar`

`GetEnvVar`

`ListEnvVars`

`DeleteEnvVar`

`ImportEnvVars`

`GetScriptEnv`

`UpdateScriptEnv`

`ListTemplates`

`GetTemplate`

`HealthCheck`