Scripts and Versioning API

Last validated: 2026-05-14

This page covers script lifecycle APIs:

• Script metadata CRUD
• Draft save/compile/test
• Publish and rollback
• Version inspection and code retrieval

1) Script Metadata APIs

CreateScript arguments and behavior

Request fields:

• name (required): tenant-unique script identifier.
• description: human-readable purpose.
• tags[]: free-form categorization for filtering.
• from_template: template ID to bootstrap draft content.
• labels[]: structured key-to-values metadata.
• env{}: initial per-script env overlay map.

Use cases:

• Start an empty script and author draft manually.
• Bootstrap from a trusted template and customize.
• Attach ownership labels for ops and governance.

Behavior notes:

• When from_template is provided, runtime creates the script and seeds draft DSL from the template.
• Initial env map becomes script overlay state.

ListScripts arguments and behavior

Request fields:

• page_size, page_token
• tags[]: all listed tags must match.
• labels[]: any matching key/value pair passes.

Behavior notes:

• Filtering works.
• Pagination token progression is currently limited (partial status).

2) Draft and Version APIs

SaveScriptDraft

Request fields:

• name (required)
• dsl_content or yaml_content

Use cases:

• Save .scriptum source while authoring.
• Upload pre-compiled YAML IR (advanced pipelines).

CompileScriptDraft

Request fields:

• name (required)

Response highlights:

• success, error
• diagnostics[]: line, column, severity, hint, source line
• tools_required[]
• ast_json, ir_yaml

Use cases:

• CI compile gate before publishing.
• Tool dependency validation (tools_required).
• AST/IR debugging and generation pipelines.

TestScriptDraft

Request fields:

• name
• input_json: execution input payload as JSON string
• load_env: include merged env resolution

Use cases:

• Fast iteration without publishing.
• Integration checks on draft changes.

PublishScriptDraft

Request fields:

• name

Response:

• version: newly published immutable version number.

Use cases:

• Promote known-good draft to production.
• Release automation after compile/test pass.

RollbackScript

Request fields:

• name
• target_version

Rules:

• target_version=0 means rollback to previous superseded version.

Use cases:

• Rapid recovery from production regressions.
• Controlled revert in incident runbook.

GetScriptCode

Request fields:

• name
• version

Rules:

• version=0 returns current draft code.

Use cases:

• Build source browser UI.
• Verify exactly what version was executed.

3) End-to-End Examples

gRPC lifecycle example

# 1) Create script
grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"name":"invoice-parser","description":"Parse invoices","tags":["invoice","etl"]}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/CreateScript
 
# 2) Save draft
grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"name":"invoice-parser","dsl_content":"script invoice-parser { ... }"}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/SaveScriptDraft
 
# 3) Compile
grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"name":"invoice-parser"}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/CompileScriptDraft
 
# 4) Publish
grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"name":"invoice-parser"}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/PublishScriptDraft

HTTP contract example (gateway deployment)

# Compile draft
curl -sS -X POST "https://api.dev.dodil.io:443/v1/scriptum/scripts/invoice-parser/draft/compile" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

4) Client Guardrails

• Always compile before publish.
• Parse and surface diagnostics[] to users; avoid hiding compile detail.
• Prefer explicit version pinning (GetScriptVersion, thread version) for reproducibility.
• Treat rollback and delete as audited operations with change ticket metadata.