API Transport, Auth, and Conventions

Last validated: 2026-05-14

This page explains how clients should connect to Scriptum APIs, pass identity metadata, and interpret common request patterns.

1) Service Access Model

Scriptum in this repository is gRPC-first.

Business APIs are served via gRPC (dodil.scriptum.v1.ScriptumService).
The proto includes HTTP annotations for gateway/transcoding compatibility.
The local scriptum-api process exposes only management HTTP endpoints directly:
- /health
- /ready
- /metrics

Practical meaning:

Use gRPC (or CLI) for all script/thread/env business operations.
Use HTTP only for management probes unless your deployment adds a gRPC-HTTP gateway.

2) Authentication and Tenant Context

Scriptum API calls expect these metadata headers:

authorization: Bearer <token>
x-organization-id: <org-id>
x-organization-name: <org-name> (optional but recommended)

gRPC example (`grpcurl`)


grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -H "x-organization-name: $SCRIPTUM_ORG_NAME" \
  -d '{"page_size": 10}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/ListScripts

HTTP contract example (gateway deployment)


curl -sS "https://api.dev.dodil.io:443/v1/scriptum/scripts?page_size=10" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -H "x-organization-name: $SCRIPTUM_ORG_NAME"

Management HTTP example (dev endpoint)


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

3) Common Request Patterns

Pagination fields

Many list RPCs expose:

page_size: maximum number of items per page.
page_token: opaque token from a previous response.
next_page_token: response token for the next page.

Current runtime caveats:

Some list APIs are marked partial because next_page_token progression is limited in current implementation.

Version selection (`version` semantics)

Common convention used across Scriptum:

version = 0 means “use special default”:
- For thread creation: active script version.
- For code retrieval: draft code in GetScriptCode.
- For rollback target: previous superseded version.

JSON-in-string inputs

Some request fields carry JSON as strings:

CreateThreadRequest.input_json
TestScriptDraftRequest.input_json
ResumeThreadRequest.step_input_override_json

Use valid serialized JSON, for example:

Object: {"file":"invoice.pdf"}
Array: [1,2,3]
String: "hello"
Number: 42

Optional field selectors

Result APIs expose optional selectors:

step_path
output_only
metadata_only

These can reduce payload size and speed up polling loops.

4) Response and Streaming Conventions

Unary first, streaming fallback

Recommended pattern:

Call unary GetThreadResult.
If output_truncated=true, call StreamThreadResult.
For large step payloads, call StreamStepResult.

Chunked streams

Streaming responses send chunk envelopes with:

Metadata chunks first.
Data chunks after.
chunk_index ordering and is_final=true termination marker.

5) Runtime Behavior Notes Clients Should Handle

CreateThread.execution_mode, CreateThread.timeout, and CreateThread.callback_url are accepted by contract but currently not enforced in scheduler behavior.
ListEnvVars currently returns both keys and values (treat output as sensitive).
Some watch events documented in proto are not emitted by current runtime mapping.

6) Error Handling Guidance

Expect standard gRPC status codes for common conditions:

INVALID_ARGUMENT: malformed JSON, missing required fields, bad enum/filter values.
NOT_FOUND: unknown script, thread, tool, env key, or template.
FAILED_PRECONDITION: compile/publish flow violations, resume constraints.
UNIMPLEMENTED: RPC declared in contract but not wired (RegisterTool, GetTool, CancelThread, ListArtifacts).
UNAUTHENTICATED / PERMISSION_DENIED: token or access scope issues.

Operational client guidance:

Retry transient transport failures with backoff.
Do not retry INVALID_ARGUMENT/UNIMPLEMENTED blindly.
Preserve request IDs and thread IDs in logs for incident triage.