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

# DinoAI Programmable Agents API

<Info>
  **Prerequisites:**

  * This feature is available on workspaces with **DinoAI programmable agents** enabled.
  * Requests must be authenticated with a Paradime API key that has access to the DinoAI Agents API.
  * Use the GraphQL endpoint shown to you when you generate your API key — it is region-specific (for example `api.paradime.io` or `api.us.paradime.io`).
</Info>

<Info>
  The example below authenticates with an **account API key** — pass `Authorization: Bearer <token>` and `X-Paradime-Workspace: <workspace_uid>` (the account key starts with `prdm_cmp_`). Legacy **workspace API keys** are still supported: send `X-API-KEY` and `X-API-SECRET` headers instead. See API Keys.
</Info>

The DinoAI Agents GraphQL API lets you drive **DinoAI programmable agents** directly over HTTP.

This API offers a comprehensive set of operations to trigger agent runs from YAML-defined agents, send ad-hoc prompts, follow up on a live session with new messages, and poll for run state.

### **Trigger an agent run**

Triggers a DinoAI programmable agent run. At least one of `agent` or `message` must be provided.

<Tabs>
  <Tab title="Args">
    **`agent`** *`(String)`*: Name of the YAML-defined agent to load (matches the file name under `.dinoai/agents/` without the `.yml` extension).

    **`message`** *`(String)`*: Custom prompt appended to the agent's context. When only `agent` is provided, the run starts with the agent's role/goal/backstory.

    **`slack`** *`(DinoAiAgentSlackInput)`*: Optional Slack routing for this run. If provided, **both** subfields are required.

    * **`channel`** *`(String!)`*: Slack channel ID the run should post into (e.g. `"C0123456789"`).
    * **`threadTs`** *`(String!)`*: Slack thread timestamp the run should reply in (e.g. `"1714142436.001200"`).

    ```graphql theme={"system"}
    mutation TriggerDinoaiAgentRun(
      $agent: String
      $message: String
      $slack: DinoAiAgentSlackInput
    ) {
      triggerDinoaiAgentRun(agent: $agent, message: $message, slack: $slack) {
        ok
        agentSessionId
        status
      }
    }
    ```
  </Tab>

  <Tab title="Returns">
    *`TriggerDinoAiAgentRun`*

    * **`ok`** *`(Boolean!)`*: Whether the run was accepted.
    * **`agentSessionId`** *`(String!)`*: The session ID for the new run. Use this for follow-ups and polling.
    * **`status`** *`(String!)`*: Always `"queued"` on accept. Poll `dinoaiAgentRun` to track live status.

    ```json theme={"system"}
    {
      "agent": "data-quality-checker",
      "message": "Check stg_orders for missing not_null tests.",
      "slack": {
        "channel": "C0123456789",
        "threadTs": "1714142436.001200"
      }
    }
    ```
  </Tab>
</Tabs>

### **Send a follow-up message**

Sends a follow-up message to an active DinoAI agent session. The agent pod stays alive for up to 24 hours since the last message; follow-ups resume the same conversation with full context.

<Tabs>
  <Tab title="Args">
    **`agentSessionId`** *`(String!)`*: The session ID of the running agent.

    **`message`** *`(String!)`*: The follow-up message to send.

    ```graphql theme={"system"}
    mutation SendDinoaiAgentMessage(
      $agentSessionId: String!
      $message: String!
    ) {
      sendDinoaiAgentMessage(agentSessionId: $agentSessionId, message: $message) {
        ok
        agentSessionId
        status
      }
    }
    ```
  </Tab>

  <Tab title="Returns">
    *`SendDinoAiAgentMessage`*

    * **`ok`** *`(Boolean!)`*: Whether the message was accepted.
    * **`agentSessionId`** *`(String!)`*: The session ID the message was attached to.
    * **`status`** *`(String!)`*: Always `"queued"` on accept.

    ```json theme={"system"}
    {
      "agentSessionId": "xwzdneft6emspe0f",
      "message": "Now also check stg_customers and post a summary to Slack."
    }
    ```
  </Tab>
</Tabs>

### **Get an agent run**

Fetches the current state of a DinoAI agent run.

<Tabs>
  <Tab title="Args">
    **`agentSessionId`** *`(String!)`*: The session ID returned by `triggerDinoaiAgentRun` or `sendDinoaiAgentMessage`.

    ```graphql theme={"system"}
    query DinoaiAgentRun($id: String!) {
      dinoaiAgentRun(agentSessionId: $id) {
        ok
        agentSessionId
        status
        messages {
          ts
          role
          content
        }
        childSessionIds
        workspaceUid
      }
    }
    ```
  </Tab>

  <Tab title="Returns">
    *`DinoAiAgentRun`*

    * **`ok`** *`(Boolean!)`*: Whether the lookup succeeded.
    * **`agentSessionId`** *`(String!)`*: The session ID.
    * **`status`** *`(DinoAiAgentRunStatus!)`*: One of `QUEUED`, `RUNNING`, `COMPLETED`, `FAILED`.
    * **`messages`** *`([DinoAiAgentMessage!]!)`*: Full conversation transcript. Each message has:
      * **`ts`** *`(Float!)`*: Unix epoch timestamp (seconds, fractional).
      * **`role`** *`(String!)`*: Author role (e.g. `user`, `assistant`).
      * **`content`** *`(String!)`*: Message body.
    * **`childSessionIds`** *`([String!]!)`*: Session IDs of sub-agents spawned during the run.
    * **`workspaceUid`** *`(String!)`*: Workspace the run belongs to.

    ```json theme={"system"}
    {
      "id": "xwzdneft6emspe0f"
    }
    ```
  </Tab>
</Tabs>

**Example: curl**

```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 TriggerDinoaiAgentRun($agent: String, $message: String, $slack: DinoAiAgentSlackInput) { triggerDinoaiAgentRun(agent: $agent, message: $message, slack: $slack) { ok agentSessionId status } }",
    "variables": {
      "agent": "data-quality-checker",
      "message": "Focus on stg_orders",
      "slack": {
        "channel": "C0123456789",
        "threadTs": "1714142436.001200"
      }
    }
  }'
```


## Related topics

- [DinoAI Programmable Agents](/developers/python-sdk/modules/dinoai-programmable-agents.md)
- [Paradime DinoAI Agent Trigger](/products/bolt/creating-schedules/command-settings/paradime-dinoai-agent-trigger.md)
- [DinoAI CLI](/developers/paradime-cli/dinoai-cli.md)
- [DinoAI Agent](/guides/paradime-101/getting-started-with-the-paradime-ide/dinoai-accelerating-your-analytics-engineering-workflow/dinoai-agent/index.md)
- [Programmable Agents](/products/dino-ai/programmable-agents/index.md)