Triggering from the API

Programmable Agents can be triggered from your own code over GraphQL or with the Paradime Python SDK. The endpoints are the same — pick whichever fits your stack.

GraphQL — full reference and cURL examples in Developers → GraphQL API → DinoAI Programmable Agents API.
Python SDK — full reference and Python examples in Developers → Python SDK → DinoAI Programmable Agents.

Prerequisites:

An agent defined under .dinoai/agents/.yml in your repository — see YAML Configuration.
An API key with DinoAI Agent capabilities.

GraphQL — quick example

Authenticate with an Account API Key (recommended): pass Authorization: Bearer <token> and X-Paradime-Workspace: <workspace_uid>. Legacy Workspace API Keys still work with X-API-KEY / X-API-SECRET headers instead. See Authentication.

curl -X POST "$PARADIME_API_ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PARADIME_API_TOKEN" \
  -H "X-Paradime-Workspace: $PARADIME_WORKSPACE_UID" \
  -d '{
    "query": "mutation Trigger($agent: String, $message: String) { triggerDinoaiAgentRun(agent: $agent, message: $message) { ok agentSessionId status } }",
    "variables": {"agent": "data-quality-checker", "message": "Focus on stg_orders"}
  }'

Save the returned agentSessionId and poll with dinoaiAgentRun(agentSessionId: $id) until status reaches a terminal state: COMPLETED, FAILED, or EXPIRED (the agent pod never started). The poll response also returns messages, childSessionIds, and workspaceUid. Select steps to follow each tool call while the agent works, and startupSteps for the start-up checklist while its environment boots. Two other arguments are worth knowing:

baseBranch starts the run from a specific git branch or commit.
modelFamily pins the run to a model family, overriding the agent’s own choice. An unrecognized slug still starts the run on the workspace’s default family and returns a warning field saying so.

See the full GraphQL reference for the trigger, poll, and follow-up operations.

Python SDK — quick example

from paradime import Paradime

paradime = Paradime(
    api_endpoint="API_ENDPOINT",
    api_secret="prdm_cmp_...",   # your account API key
    workspace_uid="WORKSPACE_UID",
)

# Trigger a named agent and block until it completes
run = paradime.dinoai_agents.trigger_run_and_wait(
    agent="data-quality-checker",
    message="Focus on stg_orders",
)

for msg in run.messages:
    print(f"[{msg.role}] {msg.content}")

See the full Python SDK reference for trigger_run, trigger_run_and_wait, send_message, and get_run.

The Python SDK does not wrap modelFamily yet, so use GraphQL directly to pin a run to a model family.

Use the SDK methods rather than posting raw GraphQL yourself. trigger_run accepts optional slack_channel / slack_thread (both required together) and base_branch, and raises ValueError if neither agent nor message is set. trigger_run_and_wait takes timeout (default 3600) and poll_interval (default 10) and raises DinoaiAgentRunFailedException on a failed run.

Quick Start — End-to-end first-run walkthrough
Triggering from Bolt — Alternative invocation path via a Bolt schedule
Agent-to-Agent Delegation — Multi-agent workflows

Slack Bot Agent

Programmable Agent

Bolt Pipeline Agent

Copilot

MCP Server

Context & Customization

DinoAI Tools

Settings & Credits

Triggering from the API

GraphQL — quick example

Python SDK — quick example

​GraphQL — quick example

​Python SDK — quick example

​Related

GraphQL — quick example

Python SDK — quick example

Related