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. 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