Quickstart

This quickstart uses the dgi.chat API, the shortest path from an app you own to a DGI answer. Nothing to install: DGI's workflows are started like any other workflow.

Before you start

• An Orkestia organization, and a token for a member of it. See Authentication. For end users of your app, use your app's token from Sign in with Orkestia.
• At least one workflow you want DGI to use. This page uses ticket.*; replace it with your own namespace, for example acme.order.*.
• An organization admin or owner for step 1. The other steps work for any member, and for end users of your app.

API="https://workflow-api.orkestia.dev"
AUTH="Authorization: Bearer $TOKEN"

run() {  # start a workflow, wait until it ends, print its output
  wid=$(curl -s -X POST "$API/api/workflows/start" -H "$AUTH" -H 'Content-Type: application/json' \
          -d "{\"workflow_type\": \"$1\", \"initial_data\": $2}" | jq -r .workflow_id)
  until curl -s "$API/api/workflows/$wid" -H "$AUTH" | jq -e '.is_terminal' >/dev/null; do sleep 1; done
  curl -s "$API/api/workflows/$wid" -H "$AUTH" | jq .state_data
}

1. Save a profile (once)

The profile is the scope every turn runs under: which workflows DGI may use, and how it decides.

run dgi.chat.profile.save '{
  "name": "Support",
  "allowed_workflow_types": ["ticket.*"],
  "suggestions": [{"label": "My open tickets", "prompt": "list my open tickets"}],
  "locale": "en"
}'
# -> {"profile_uuid": "7c1e…", "created": true, ...}

Keep profile_uuid: your app sends it with every turn. The LLM is off by default (llm_fallback: false), so anything Jev cannot decide comes back as chips. Every field is in Option D.

2. Send a message

run dgi.chat.turn '{"profile_uuid": "7c1e…", "message": "which tickets are open?"}'
# -> {"conversation_uuid": "3f9a…",
#     "text": "12 open tickets.",
#     "ui": {"v": 1, "ui_id": "0b6f…", "renderer": "table",
#            "render": {"kind": "table", "title": "Open tickets", "columns": [...], "rows": [...],
#                       "row_actions": [{"label": "Details"}]}},
#     "suggestions": ["Only high priority", "Assign to me"],
#     "decision_path": "jev:…"}

Send conversation_uuid with the next message to continue the same conversation.

3. Draw the answer

Show text as markdown. If ui is not null, draw it by its renderer: every renderer and its fields are in the card catalog, and the card contract is published as JSON Schema. Show suggestions as buttons that send their label as the next message.

4. Answer the card

When the person acts on the card, send its ui_id, the action and the values. For example, a click on the first row's Details:

run dgi.chat.respond '{"conversation_uuid": "3f9a…", "ui_id": "0b6f…",
                       "action": "row_action", "values": {"row": 0, "action": "Details"}}'

A change works the same way. Ask for one ("assign ticket 42 to Ana") and DGI answers with a form for missing inputs, then a confirm card. The person presses Confirm, and your app sends:

run dgi.chat.respond '{"conversation_uuid": "3f9a…", "ui_id": "<the confirm card id>", "action": "confirm"}'

The server runs the proposal it stored, not anything your app sends back. A confirm is valid once, for 30 minutes, and only for the person it was issued to.

Try it from an AI assistant

With an assistant connected over MCP:

Save a dgi.chat profile named "Support" that may only use ticket.* workflows, with the LLM off. Show me the call and wait for my confirmation.

Using that profile, send the DGI turn "which tickets are open?" and show me the card that comes back.

Draw the same data as a bar chart by priority with dgi.view.render, no conversation.

Next steps

• Turn on the LLM for open questions: llm_fallback: true in the profile. It runs on your organization's AI provider.
• Add default_inputs so DGI pre-fills values your app already knows.
• Put the same cards on a live page: Living Surfaces.
• Read Trust and safety before you show it to customers.