Invocation & Executions — API Reference

Package: dodil.ignite.v1 · Service: ComputeService

Invoking an app runs its active version in a pod and returns the pod’s HTTP response. The request carries an invocation envelope — an HttpContext (verb, path, query, headers) plus a body. If the app is scaled to zero, the first call wakes it (see Cold starts).

gRPC reaches every method at dodil.ignite.v1.ComputeService/<Method> on $IGNITE_GRPC; the HTTP gateway mirrors each one. See Conventions → Using gRPC for setup. gRPC requests use the proto field names (snake_case); HTTP uses pbjson (camelCase). int64/uint64 are JSON strings, enums are wire-name strings; responses render camelCase.

Invocation surfaces

Three ways to reach an app, differing in framing, auth, and whether a queryable Execution record is created:

Use a direct FQDN for the lowest latency from browsers/webhooks/standard HTTP clients; the Invoke RPC when you want structured framing + an execution_id to correlate logs; InvokeAsync for fire-and-forget work you’ll poll or watch.

Direct FQDN invocation

Every published app gets one public URL per declared port, returned on AppMeta.public_urls. This is the fastest surface — a plain HTTP call straight to the pod, with no API hop or response framing.

• Format: `<app>-<org>.ignite.dodil.cloud` for the default port 80, or `<app>-<org>-<port>.ignite.dodil.cloud` for any other port. A . in the app name is encoded as -dot- to keep a single DNS label.
• When populated: only after the first publish (active_version > 0), in ports order — public_urls[0] is the primary URL.
• Auth: still required — direct FQDNs validate the Authorization: Bearer token and enforce org match. They are not anonymous. The exception is apps in the public org, which any authenticated caller may invoke.
• No execution record: a direct call is proxied straight to the pod (the gateway still counts it for billing), so there’s nothing to fetch with GetExecution afterward — use InvokeAsync if you need a record.

# the pod's raw response — call any path/verb your app serves
curl -sS -X POST "https://my-data-processor-acme-corp.ignite.dodil.cloud/" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "key": "value" }'

Invoke

Server-streaming. The gateway forwards the envelope to the pod and streams back the response in frames, in a fixed order:

1. head — once, first: status_code, response_headers, and an execution_id.
2. chunk — 0..N frames carrying the response body bytes, in order.
3. trailer — once, last: total_body_bytes, duration_ms, and any HTTP trailers.

Non-streaming apps emit one chunk + the trailer. The stream may end with a gRPC error instead of a trailer if the pod fails mid-flight; chunks already delivered are kept. Dropping the stream disconnects the pod.

Invoke does not create a queryable execution record. The execution_id in the head frame is for log correlation only (echoed to the pod as X-Ignite-Execution-Id) — GetExecution will not find it. If you need a record to poll or audit later, use InvokeAsync.

Request

curl -sS -X POST "https://api.dev.dodil.io/v1/ignite/app/acme-corp/my-data-processor/invoke" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "http": { "method": "HTTP_METHOD_POST", "path": "/", "headers": { "content-type": "application/json" } },
    "body": "eyJrZXkiOiAidmFsdWUifQ=="
  }'

rpc Invoke(InvokeRequest) returns (stream InvokeResponse);
 
message InvokeRequest {
  string organization_name = 1;
  string app_name = 2;
  HttpContext http = 3;       // verb/path/query/headers; absent → POST "/"
  bytes body = 4;             // raw request body; JSON for most apps
  int64 timeout_ms = 5;       // gateway↔pod deadline; 0 = app default
}
 
// HttpContext (ignite_common.proto)
message HttpContext {
  HttpMethod method = 1;          // HTTP_METHOD_UNSPECIFIED → POST
  string path = 2;                // empty → "/"
  string query = 3;               // raw query string, no leading "?"
  map<string,string> headers = 4; // hop-by-hop headers stripped
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -d '{
    "organization_name": "acme-corp",
    "app_name": "my-data-processor",
    "http": { "method": "HTTP_METHOD_POST", "path": "/", "headers": { "content-type": "application/json" } },
    "body": "eyJrZXkiOiAidmFsdWUifQ=="
  }' \
  $IGNITE_GRPC \
  dodil.ignite.v1.ComputeService/Invoke
# prints a stream of frames: one head, then chunk(s), then a trailer

Response

// Sequence: head (once, first) → 0..N chunk → trailer (once, last).
message InvokeResponse {
  oneof payload {
    InvokeHead    head    = 1;
    bytes         chunk   = 2;
    InvokeTrailer trailer = 3;
  }
}
 
message InvokeHead {
  int32 status_code = 1;                     // pod's HTTP status
  map<string,string> response_headers = 2;
  string execution_id = 3;                   // log-correlation id (not a stored record)
}
 
message InvokeTrailer {
  int64 total_body_bytes = 1;
  int64 duration_ms = 2;                     // request-in → last-byte-out; includes any cold start
  map<string,string> trailers = 3;
}

Async invocation & tracking executions

For fire-and-forget work, InvokeAsync returns an execution_id immediately and creates an Execution record — then you GetExecution to poll it or WatchExecution to stream its progress to a terminal state. (Invoke, by contrast, creates no record.)

InvokeAsync

Takes the same InvokeRequest as Invoke, returns just the id.

curl -sS -X POST "https://api.dev.dodil.io/v1/ignite/app/acme-corp/my-data-processor/invoke-async" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "body": "eyJrZXkiOiAidmFsdWUifQ==" }'
# → { "executionId": "exec_01HZX9..." }

rpc InvokeAsync(InvokeRequest) returns (InvokeAsyncResponse);
// InvokeRequest is identical to Invoke — see above.
 
message InvokeAsyncResponse {
  string execution_id = 1;                   // poll GetExecution / WatchExecution with this
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -d '{
    "organization_name": "acme-corp",
    "app_name": "my-data-processor",
    "body": "eyJrZXkiOiAidmFsdWUifQ=="
  }' \
  $IGNITE_GRPC \
  dodil.ignite.v1.ComputeService/InvokeAsync

GetExecution

Fetch the status and result of one execution by ID. Works for records created by InvokeAsync (and model / API-proxy paths) — not for streaming Invoke calls, which create no record.

curl -sS "https://api.dev.dodil.io/v1/ignite/executions/exec_01HZX9..." \
  -H "Authorization: Bearer $DODIL_TOKEN"

{
  "execution": {
    "id": "exec_01HZX9...",
    "appId": "acme-corp/my-data-processor",
    "status": "EXECUTION_STATUS_COMPLETED",
    "result": "eyJvayI6IHRydWV9",
    "metrics": { "executionMs": "142", "resultSizeBytes": "11", "resourceTier": "Medium" },
    "functionVersion": 3,
    "appName": "my-data-processor"
  }
}

rpc GetExecution(GetExecutionRequest) returns (GetExecutionResponse);
message GetExecutionRequest { string execution_id = 1; }
 
message GetExecutionResponse { Execution execution = 1; }
 
// Execution (ignite_common.proto)
message Execution {
  string id = 1;
  string app_id = 2;
  ExecutionStatus status = 3;     // PENDING | RUNNING | COMPLETED | FAILED | TIMEOUT
  bytes result = 4;               // JSON-encoded result data
  string error = 5;
  ExecutionMetrics metrics = 6;   // execution_ms, result_size_bytes, resource_tier
  int64 started_at_ms = 7;
  int64 completed_at_ms = 8;
  uint32 function_version = 9;    // version that ran
  string app_name = 11;
  string logs = 12;               // inline truncated logs (max 4KB)
  string error_class = 13;        // "client" | "user_code" | "model_config" | "model_upstream" | "platform"
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -d '{ "execution_id": "exec_01HZX9..." }' \
  $IGNITE_GRPC \
  dodil.ignite.v1.ComputeService/GetExecution

WatchExecution

Server-streaming. Sends the current Execution immediately, then every update until a terminal state (COMPLETED / FAILED / TIMEOUT). For streaming apps, output arrives as data-only frames (execution absent, output_chunk set) before the terminal response.

curl -sN "https://api.dev.dodil.io/v1/ignite/executions/exec_01HZX9.../watch" \
  -H "Authorization: Bearer $DODIL_TOKEN"
# chunked response — one JSON object per update, ending with the terminal execution

rpc WatchExecution(WatchExecutionRequest) returns (stream WatchExecutionResponse);
message WatchExecutionRequest { string execution_id = 1; }
 
message WatchExecutionResponse {
  Execution execution = 1;     // present on state updates + the terminal response
  bytes output_chunk = 2;      // streaming apps only; data-only frames (execution absent)
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -d '{ "execution_id": "exec_01HZX9..." }' \
  $IGNITE_GRPC \
  dodil.ignite.v1.ComputeService/WatchExecution

GetExecutionStats

Per-app execution counts bucketed over time (the Stats-tab graph). Backed by Prometheus; the range is capped at 90 days and clamped server-side.

Request

curl -sS "https://api.dev.dodil.io/v1/ignite/app/acme-corp/my-data-processor/stats/executions?bucketSecs=86400" \
  -H "Authorization: Bearer $DODIL_TOKEN"

rpc GetExecutionStats(GetExecutionStatsRequest) returns (GetExecutionStatsResponse);
 
message GetExecutionStatsRequest {
  string organization_name = 1;
  string app_name = 2;
  int64 since_ms = 3;       // inclusive lower bound; default now - 7d, clamped to 90d
  int64 until_ms = 4;       // exclusive upper bound; default now
  int32 bucket_secs = 5;    // 3600 (1h) | 21600 (6h) | 86400 (1d); default 86400
}

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -d '{ "organization_name": "acme-corp", "app_name": "my-data-processor", "bucket_secs": 86400 }' \
  $IGNITE_GRPC \
  dodil.ignite.v1.ComputeService/GetExecutionStats

Response

message GetExecutionStatsResponse {
  repeated ExecutionBucket buckets = 1;
  int32 bucket_secs = 2;                 // width actually used (server may clamp)
  repeated string partial_clusters = 3;  // clusters whose Prometheus didn't respond; empty = complete
}
 
message ExecutionBucket {
  int64 timestamp_ms = 1;   // bucket start (inclusive)
  int32 completed = 2;
  int32 failed = 3;
  int32 timeout = 4;
}

Cold starts vs warm pods

Ignite apps scale to zero when idle, so an invocation is either warm (a pod is already running) or cold (none is — one has to start).

• Cold path. The first request to a scaled-to-zero app is caught by the platform’s KEDA HTTP interceptor, which holds the connection open while a pod is started (0→1) and becomes ready, then proxies the request through. The call isn’t rejected — it just waits. The gateway waits up to the cold-start budget (default 600s, IGNITE_COLD_START_BUDGET_SECS) for the pod; the total per-request deadline is your app timeout + the cold-start budget. The trailer.duration_ms on an Invoke includes this wait.
• Warm path. Once running, requests skip straight to the pod. An app stays up for scaledown_period_secs (default 300s) after traffic drops, then KEDA scales it back toward zero. Long-idle apps may have their underlying resources torn down; the next request re-provisions them (a bit slower than a plain wake-up).
• Keeping pods warm. Set ScalingConfig.reserved_capacity > 0 to keep that many pods always running — those serve the first N concurrent requests with no cold start, and the app is exempt from idle teardown. There is no separate “pre-warm” call.

Scaling configuration

An app scales horizontally on demand. The knobs live on ScalingConfig, set at CreateApp or UpdateAppConfig; the platform maps them onto KEDA’s HTTP autoscaler.

How a replica gets added. The autoscaler computes desired_replicas = ceil(observed_per_pod / scale_threshold), clamped to [reserved_capacity, max_replicas]. With REQUEST_RATE, observed_per_pod is average requests/second per pod (1-minute window); with CONCURRENCY, it’s in-flight requests per pod. Activation from zero is binary — any inbound request triggers it.

Pick the metric to match the workload. CONCURRENCY suits variable-duration work (LLM inference, image processing, long jobs); REQUEST_RATE suits short, uniform requests. The effective max_replicas is min(your value, platform cap) — raise the platform cap with ops if you need more.

See also

• Apps — app metadata, config, and state
• Drafts — attach code, compile, publish
• Observability — logs, events, and replicas
• Core Concepts → Execution · → Resources & scaling
• grpcurl reference — flags + reflection fallbacks