Skip to Content
Conventions

API Conventions

Use this page as the baseline for all Ignite API calls.

Transport and Endpoints

Ignite has a dual surface: every service is reachable over gRPC and over HTTP/pbjson (JSON transcoding via google.api.http).

There are two HTTP path families:

  • /v1/ignite/... — Compute, Build, and Secret services.
  • /v1/... (OpenAI/Cohere-style) — the Model service (/v1/chat/completions, /v1/embeddings, /v1/models, …).

All services share the flat package dodil.ignite.v1.

The HTTP API is the simplest way in — plain JSON over HTTPS, nothing to install — and it’s the default tab in these docs. Every method is also available over gRPC (see Using gRPC).

Two endpoint families:

SurfaceEndpoint
HTTP (api)https://api.dodil.io
gRPC (rpc)rpc.dodil.io:443

Every example in these docs runs against these production endpoints. Export your token once and they work:

export DODIL_TOKEN="<your-token>"     # bearer token for every authenticated call

Request size. Requests to api.dodil.io and rpc.dodil.io are limited to 10 MB; larger payloads are rejected with 413. For bigger files, upload them to object storage (DataK³ ) and pass a reference, or deploy code through Git + CI.

Auth

Send one header on authenticated requests:

  • Authorization: Bearer <token>

Your organization context is encoded in the bearer token’s claims — you don’t send an org id yourself. The gateway derives it and injects x-organization-name for downstream services.

Get a token with dodil auth login (interactive), or programmatically — apps and agents use the OAuth client-credentials flow. See Get an Access Token .

A few RPCs are public and need no auth: ListPublicCatalog, GetPublicCatalogDetail, HealthCheck, and the Model catalog reads (ListModels, GetModel).

Using gRPC

Every method is also reachable over gRPC as dodil.ignite.v1.<Service>/<Method> (e.g. dodil.ignite.v1.ComputeService/ListApps). Install grpcurl (brew install grpcurl) and set the endpoint once:

export IGNITE_GRPC="rpc.dodil.io:443"

grpcurl discovers the schema via server reflection — no .proto file needed:

grpcurl -H "Authorization: Bearer $DODIL_TOKEN" $IGNITE_GRPC list

If your endpoint doesn’t expose reflection, point grpcurl at the proto instead — grpcurl -proto ignite_compute.proto -H "Authorization: Bearer $DODIL_TOKEN" $IGNITE_GRPC ....

Field-name casing. gRPC request bodies use the proto field names — snake_case like organization_name, exactly as the .proto blocks in these docs show (grpcurl also accepts camelCase). Responses render in camelCase — that’s grpcurl’s default JSON output. The HTTP surface is camelCase both ways. So within a gRPC example: the request matches the proto block (snake_case), the response is camelCase.

pbjson Wire Notes

When using the HTTP/JSON surface:

  • Field names are camelCase.
  • int64 values are encoded as JSON strings.
  • Enums are wire-name strings (e.g. "VERSION_STATUS_ACTIVE").
  • In ModelService, OpenAI-polymorphic fields (where a value may be a string, object, or array) are carried as google.protobuf.Value, so the JSON shape matches the OpenAI/Cohere request exactly.

Streaming

Several RPCs stream:

  • Server-streaming (works over both gRPC and HTTP): Invoke, WatchExecution, StreamAppLogs, StreamAppEvents, StreamCompileLogs, StreamChatCompletion, StreamRerank, StreamInfer, StreamBuildLogs.
  • Client-streaming, gRPC only: UploadBuildContext (Build). The HTTP gateway cannot transcode client-streaming RPCs, so it is unavailable over HTTP.

App names

Ignite normalizes the name you give an app: it is lowercased, other characters are mapped to valid ones, and a name ending in -<number> gets -app appended (lab-erp-1 becomes lab-erp-1-app). Use the name the create call returns, not the one you sent, in URLs, IAM grants, and secret names. App URLs take the form <app>-<org>.ignite.dodil.cloud; copy the host from public_urls in dodil ignite app get <app> rather than building it by hand.

Usage limits

Each organization’s plan sets hard usage caps, and they are enforced. A call that would exceed one is refused with gRPC RESOURCE_EXHAUSTED, carrying x-ignite-quota metadata and a message of the form “Your organization has used its … allowance …”. Treat it as a billing limit, not a transient error: retrying won’t help until the allowance resets or the plan changes.

See also

OverviewOverview