> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paradime.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggering from the API

> Trigger DinoAI Programmable Agents from your own code using the Paradime GraphQL API or Python SDK, so agent runs slot into Airflow, Lambda, or webhooks.

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**](/developers/graphql-api/api-reference/dinoai-programmable-agents-api) — full reference and cURL examples in Developers → GraphQL API → DinoAI Programmable Agents API.
* [**Python SDK**](/developers/python-sdk/modules/dinoai-programmable-agents) — full reference and Python examples in Developers → Python SDK → DinoAI Programmable Agents.

<Info>
  **Prerequisites:**

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

#### 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](/developers/graphql-api/authentication).

```bash theme={"system"}
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`. See the full GraphQL reference for the trigger, poll, and follow-up operations.

***

#### Python SDK — quick example

```python theme={"system"}
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`.

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

#### Related

* [Quick Start](/products/dino-ai/programmable-agents/index) — End-to-end first-run walkthrough
* [Triggering from Bolt](/products/dino-ai/programmable-agents/triggering-from-bolt) — Alternative invocation path via a Bolt schedule
* [Agent-to-Agent Delegation](/products/dino-ai/programmable-agents/agent-to-agent-delegation) — Multi-agent workflows


## Related topics

- [Triggering from Bolt](/products/dino-ai/programmable-agents/triggering-from-bolt.md)
- [Bolt API](/products/bolt/bolt-api.md)
- [Bolt API and schedule trigger errors](/get-help/error-list/bolt-api-and-schedule-trigger-errors.md)
- [Configuration Reference](/products/bolt/creating-schedules/schedules-as-code/configuration-reference.md)
- [Bolt runs agents natively, no API keys](/changelog/2026-08-05/bolt-runs-agents-natively.md)