Scripts & Versioning — API Reference

curl -sS -X POST "https://api.dev.dodil.io/v1/scriptum/scripts" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-etl-pipeline",
    "description": "ETL pipeline that ingests CSV files and writes to S3",
    "tags": ["etl"],
    "fromTemplate": "hello_world"
  }'

rpc CreateScript(CreateScriptRequest) returns (CreateScriptResponse);
 
message CreateScriptRequest {
  string name = 1;                       // unique per tenant
  string description = 2;
  repeated string tags = 3;
  string from_template = 4;              // bootstrap from a template ID
  repeated LabelEntry labels = 5;        // { key, values[] }
  map<string, string> env = 6;          // initial per-script env overlay
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -d '{
    "name": "my-etl-pipeline",
    "description": "ETL pipeline that ingests CSV files and writes to S3",
    "tags": ["etl"],
    "from_template": "hello_world"
  }' \
  rpc.dev.dodil.io:443 \
  dodil.scriptum.v1.ScriptumService/CreateScript

{
  "name": "my-etl-pipeline",
  "createdAtMs": "1748390400000"
}

message CreateScriptResponse {
  string name = 1;
  int64 created_at_ms = 2;
}

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

rpc ListScripts(ListScriptsRequest) returns (ListScriptsResponse);
 
message ListScriptsRequest {
  int32 page_size = 1;
  string page_token = 2;
  repeated string tags = 3;
  repeated LabelEntry labels = 4;
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -d '{ "page_size": 20, "tags": ["etl"] }' \
  rpc.dev.dodil.io:443 \
  dodil.scriptum.v1.ScriptumService/ListScripts

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

rpc GetScript(GetScriptRequest) returns (Script);
 
message GetScriptRequest {
  string name = 1;
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -d '{ "name": "my-etl-pipeline" }' \
  rpc.dev.dodil.io:443 \
  dodil.scriptum.v1.ScriptumService/GetScript

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

rpc DeleteScript(DeleteScriptRequest) returns (DeleteScriptResponse);
 
message DeleteScriptRequest { string name = 1; }

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -d '{ "name": "my-etl-pipeline" }' \
  rpc.dev.dodil.io:443 \
  dodil.scriptum.v1.ScriptumService/DeleteScript

curl -sS -X POST "https://api.dev.dodil.io/v1/scriptum/scripts/my-etl-pipeline/draft" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "dslContent": "script my_pipeline {\n  do fetch_data with http_request ...\n}"
  }'

rpc SaveScriptDraft(SaveScriptDraftRequest) returns (SaveScriptDraftResponse);
 
message SaveScriptDraftRequest {
  string name = 1;
  string dsl_content = 2;        // DSL source (provide this or yaml_content)
  string yaml_content = 3;       // pre-compiled YAML IR
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -d '{
    "name": "my-etl-pipeline",
    "dsl_content": "script my_pipeline { do fetch_data with http_request ... }"
  }' \
  rpc.dev.dodil.io:443 \
  dodil.scriptum.v1.ScriptumService/SaveScriptDraft

{
  "status": "SCRIPT_VERSION_STATUS_DRAFT",
  "updatedAtMs": "1748390400000"
}

message SaveScriptDraftResponse {
  ScriptVersionStatus status = 1;
  int64 updated_at_ms = 2;
}

curl -sS -X POST "https://api.dev.dodil.io/v1/scriptum/scripts/my-etl-pipeline/draft/compile" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -H "Content-Type: application/json" \
  -d '{}'

rpc CompileScriptDraft(CompileScriptDraftRequest) returns (CompileScriptDraftResponse);
 
message CompileScriptDraftRequest { string name = 1; }

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -d '{ "name": "my-etl-pipeline" }' \
  rpc.dev.dodil.io:443 \
  dodil.scriptum.v1.ScriptumService/CompileScriptDraft

{
  "success": false,
  "error": "type error in step fetch_data",
  "toolsRequired": ["http_request"],
  "diagnostics": [
    {
      "line": 12,
      "col": 5,
      "message": "unknown field 'ur' on http_request input",
      "hint": "did you mean 'url'?",
      "severity": "error",
      "sourceLine": "    do fetch_data with http_request(ur: input.source)"
    }
  ],
  "astJson": "",
  "irYaml": ""
}

message CompileScriptDraftResponse {
  bool success = 1;
  string error = 2;
  repeated string tools_required = 3;
  repeated CompileDiagnostic diagnostics = 4;
  string ast_json = 5;          // compiler AST (your data, JSON string)
  string ir_yaml = 6;           // compiled YAML IR (your data, string)
}

curl -sS -X POST "https://api.dev.dodil.io/v1/scriptum/scripts/my-etl-pipeline/draft/test" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "inputJson": "{\"source\": \"data.csv\"}",
    "loadEnv": true
  }'

rpc TestScriptDraft(TestScriptDraftRequest) returns (TestScriptDraftResponse);
 
message TestScriptDraftRequest {
  string name = 1;
  string input_json = 2;        // your data, as a JSON string
  bool load_env = 3;
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -d '{
    "name": "my-etl-pipeline",
    "input_json": "{\"source\": \"data.csv\"}",
    "load_env": true
  }' \
  rpc.dev.dodil.io:443 \
  dodil.scriptum.v1.ScriptumService/TestScriptDraft

{
  "threadId": "thr_abc123",
  "status": "THREAD_STATUS_RUNNING"
}

message TestScriptDraftResponse {
  string thread_id = 1;
  ThreadStatus status = 2;
}

curl -sS -X POST "https://api.dev.dodil.io/v1/scriptum/scripts/my-etl-pipeline/draft/publish" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -H "Content-Type: application/json" \
  -d '{}'

rpc PublishScriptDraft(PublishScriptDraftRequest) returns (PublishScriptDraftResponse);
 
message PublishScriptDraftRequest { string name = 1; }

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -d '{ "name": "my-etl-pipeline" }' \
  rpc.dev.dodil.io:443 \
  dodil.scriptum.v1.ScriptumService/PublishScriptDraft

curl -sS -X POST "https://api.dev.dodil.io/v1/scriptum/scripts/my-etl-pipeline/rollback" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -H "Content-Type: application/json" \
  -d '{ "targetVersion": 2 }'

rpc RollbackScript(RollbackScriptRequest) returns (RollbackScriptResponse);
 
message RollbackScriptRequest {
  string name = 1;
  int32 target_version = 2;     // 0 = previous active version
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -d '{ "name": "my-etl-pipeline", "target_version": 2 }' \
  rpc.dev.dodil.io:443 \
  dodil.scriptum.v1.ScriptumService/RollbackScript

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

rpc ListScriptVersions(ListScriptVersionsRequest) returns (ListScriptVersionsResponse);
 
message ListScriptVersionsRequest { string name = 1; }

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -d '{ "name": "my-etl-pipeline" }' \
  rpc.dev.dodil.io:443 \
  dodil.scriptum.v1.ScriptumService/ListScriptVersions

curl -sS "https://api.dev.dodil.io/v1/scriptum/scripts/my-etl-pipeline/versions/3" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG"

rpc GetScriptVersion(GetScriptVersionRequest) returns (ScriptVersion);
 
message GetScriptVersionRequest {
  string name = 1;
  int32 version = 2;
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -d '{ "name": "my-etl-pipeline", "version": 3 }' \
  rpc.dev.dodil.io:443 \
  dodil.scriptum.v1.ScriptumService/GetScriptVersion

curl -sS "https://api.dev.dodil.io/v1/scriptum/scripts/my-etl-pipeline/code/versions/1" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG"

rpc GetScriptCode(GetScriptCodeRequest) returns (GetScriptCodeResponse);
 
message GetScriptCodeRequest {
  string name = 1;
  int32 version = 2;            // 0 = current draft
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -d '{ "name": "my-etl-pipeline", "version": 1 }' \
  rpc.dev.dodil.io:443 \
  dodil.scriptum.v1.ScriptumService/GetScriptCode

{
  "version": 1,
  "dslContent": "script my_pipeline { ... }",
  "yamlContent": "steps:\n  - ...",
  "status": "SCRIPT_VERSION_STATUS_ACTIVE",
  "createdAtMs": "1748390400000"
}

message GetScriptCodeResponse {
  int32 version = 1;
  string dsl_content = 2;
  string yaml_content = 3;
  ScriptVersionStatus status = 4;
  int64 created_at_ms = 5;
}

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

rpc GetDraftInfo(GetDraftInfoRequest) returns (GetDraftInfoResponse);
 
message GetDraftInfoRequest { string name = 1; }

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-name: $DODIL_ORG" \
  -d '{ "name": "my-etl-pipeline" }' \
  rpc.dev.dodil.io:443 \
  dodil.scriptum.v1.ScriptumService/GetDraftInfo

{
  "status": "SCRIPT_VERSION_STATUS_COMPILED",
  "dslContent": "script my_pipeline { ... }",
  "yamlContent": "steps:\n  - ...",
  "error": "",
  "toolsRequired": ["http_request"],
  "updatedAtMs": "1748390400000",
  "contract": { "inputs": [], "outputs": [], "enums": [] }
}

message GetDraftInfoResponse {
  ScriptVersionStatus status = 1;
  string dsl_content = 2;
  string yaml_content = 3;
  string error = 4;
  repeated string tools_required = 5;
  int64 updated_at_ms = 6;
  ScriptContract contract = 7;
}