Templates — API Reference

Package: dodil.data.pipeline.v1 · Service: PipelineService

Templates are catalog entries from Scriptum — the recipes new pipelines spawn from. See Core Concepts → Template for the type signature.

gRPC setup — grpcurl, endpoints, reflection, and field-name casing — is covered once in Conventions → Using gRPC.

The catalog

There is no registry, manifest or seed table — the catalog is the template tree itself. Scriptum’s loader walks templates/ at boot: the directory name becomes the template’s category and the filename stem becomes its id. The count is whatever the loader finds, so treat the tables below as the shape of the catalog rather than a frozen inventory, and call ListTemplates for the live set.

The six category values are therefore the six directories: actions, core, ecommerce, embedding, financials, vision.

analysis is not a category. It exists only as a label value (labels.category), which is a different field from the top-level category the API returns and ?category= filters on. Filtering ?category=analysis matches nothing.

Core (9)

Domain-agnostic processing — classification, extraction, summarization. Warehouse-compatible: bind these to a Tables destination to land structured rows.

Embedding (10)

The embedding category holds five *_index templates and their five *_search counterparts.

Index pipelines (5)

Ingestion-side embedding pipelines. Each indexes a modality into a Vector collection. Bind these as vector pipelines.

Search pipelines (5)

Query-side counterparts to the _index templates. You rarely create these by hand: CreateVectorPipeline derives the search-side template from the index one by the *_index → *_search convention and spawns that pipeline for you, which is why one collection shows up as two rows in ListPipelines.

What’s in the vector catalog

The five index templates back the auto-embed-on-ingest vector collections — you create a collection with the _index variant via CreateVectorPipeline, and K3 derives the _search counterpart automatically. Their resolved shape:

The five search counterparts carry the same model and dimensions but declare no accepted extensions, because nothing ingests through them. object_embedding_index is the only one with a required template input: labels, a list of 1–100 open-vocabulary class prompts for the detector.

The suffix convention is not validated. CreateVectorPipeline derives <stem>_search by string surgery and never checks the catalog for it. A custom template that does not end in _index, or whose _search counterpart does not exist, yields a collection that indexes but cannot be searched — surfaced only as a server-side warning and later as a warnings[] entry on the search route.

Vision (4)

Image / video / audio analysis. All warehouse-compatible.

Ecommerce (2)

Domain templates for commerce / marketplace use cases. Both warehouse-compatible.

Financials (2)

Actions (7)

Query-time templates behind the curated AI actions surface, rather than ingest-side pipelines: chunks_synthesize_answer, collection_topic_map, object_qa, objects_compare, objects_synthesis, plan_and_run, table_qa.

Unaudited templates do not ship. Scriptum’s loader hard-skips the unaudited/ directory at boot and logs skipping unaudited templates directory, so those templates are not in the image, not returned by ListTemplates, and cannot be passed as a template_id — a pipeline referencing one fails to resolve. Names you may see quoted in older docs or tests — lease_extraction, contract_extraction, resume_parsing, content_moderation, claims_intake — are all unaudited and unavailable in production.

ListTemplates

Request

dodil data template list
dodil data template list --category embedding
dodil data template list --search ocr
dodil data template list --label warehouse_compatible=true

curl -sS "https://api.data.dodil.io/admin/templates" \
  -H "Authorization: Bearer $DODIL_TOKEN"

curl -sS "https://api.data.dodil.io/admin/templates?category=embedding" \
  -H "Authorization: Bearer $DODIL_TOKEN"

curl -sS "https://api.data.dodil.io/admin/templates?facet=table" \
  -H "Authorization: Bearer $DODIL_TOKEN"

curl -sS "https://api.data.dodil.io/admin/templates?search=ocr" \
  -H "Authorization: Bearer $DODIL_TOKEN"

rpc ListTemplates(ListTemplatesRequest) returns (ListTemplatesResponse);
 
message ListTemplatesRequest {
  map<string, string> labels = 1;             // label-equals filter
  optional string category = 2;
  optional string search = 3;                 // free-text on name/description
  reserved 4;                                 // was the `Pillar` enum
  PipelineFacet facet = 5;                    // UNSPECIFIED = whole catalog
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -d '{}' \
  $K3_GRPC \
  dodil.data.pipeline.v1.PipelineService/ListTemplates

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -d '{
    "category": "embedding"
  }' \
  $K3_GRPC \
  dodil.data.pipeline.v1.PipelineService/ListTemplates

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -d '{
    "search": "ocr"
  }' \
  $K3_GRPC \
  dodil.data.pipeline.v1.PipelineService/ListTemplates

Response

{
  "templates": [
    {
      "id": "text_embedding_index",
      "name": "Text Embedding Index",
      "description": "Resolves a source object → chunks → embeds → indexes.",
      "tags": ["embedding", "rag"],
      "toolsRequired": ["k3_vector_upsert"],
      "labels": { "category": "embedding", "modality": "text", "pillar": "vectors" },
      "category": "embedding",
      "modalities": ["text"],
      "acceptedExtensions": ["pdf", "docx", "txt", "html"],
      "acceptedContentTypes": ["application/pdf"],
      "outputKind": ""
    }
  ]
}

message ListTemplatesResponse {
  repeated Template templates = 1;
}

GetTemplate

Returns one template with its full typed ScriptContract (input fields, output schema, accepted modalities), proxied verbatim from Scriptum. K3 reads the contract server-side to validate caller-supplied template_inputs, and to resolve the schema-shaping facts — embed_model, dimensions, distance_metric, sparse_mode — when spawning a vector pipeline. Those facts come from the contract and cannot be overridden by the caller.

Request

dodil data template get text_embedding_index

curl -sS "https://api.data.dodil.io/admin/templates/text_embedding_index" \
  -H "Authorization: Bearer $DODIL_TOKEN"

rpc GetTemplate(GetTemplateRequest) returns (Template);
 
message GetTemplateRequest {
  string template_id = 1;
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -d '{
    "template_id": "text_embedding_index"
  }' \
  $K3_GRPC \
  dodil.data.pipeline.v1.PipelineService/GetTemplate

Response

A Template — see Core Concepts → Template.

Using templates in pipeline creation

A template_id from this catalog is what the three facet creators take — they create the destination and the pipeline together in one call:

For a table pipeline the template must declare @accepts_extension — the derived ingest rule’s globs come from it, and a table pipeline with none can never fire. Check acceptedExtensions on the template before you bind it.

CreatePipeline also takes a template id, via either scriptum_template or its historical alias spawn_from_template — both variants now mean the same thing, “this is the template id to dispatch”. Neither one creates a fresh Scriptum script: the worker builds the per-call env at dispatch time, so there is nothing to bake in at create. Use CreatePipeline to add a second pipeline onto a destination that already exists, or to make a free pipeline; use a facet creator to make the destination itself.

A pipeline created from a template does not ingest anything yet. Binding an ingest rule is a separate, mandatory step — see Rules.

See also

• Pipelines — spawn pipelines from templates
• Core Concepts → Template — type signature
• Core Concepts → ScriptContract — the typed I/O contract on GetTemplate
• CLI Guide → template — dodil data template list / get
• Vector — destination for embedding pipelines
• Tables — destination for warehouse_compatible templates
• grpcurl reference — full flag set + reflection-disabled fallbacks