DinoAI Programmable Agents API

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

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.

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

Returns

mutation TriggerDinoaiAgentRun(
  $agent: String
  $message: String
  $slack: DinoAiAgentSlackInput
) {
  triggerDinoaiAgentRun(agent: $agent, message: $message, slack: $slack) {
    ok
    agentSessionId
    status
  }
}

{
  "agent": "data-quality-checker",
  "message": "Check stg_orders for missing not_null tests.",
  "slack": {
    "channel": "C0123456789",
    "threadTs": "1714142436.001200"
  }
}

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.

Args

agentSessionId (String!): The session ID of the running agent.

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

Returns

mutation SendDinoaiAgentMessage(
  $agentSessionId: String!
  $message: String!
) {
  sendDinoaiAgentMessage(agentSessionId: $agentSessionId, message: $message) {
    ok
    agentSessionId
    status
  }
}

{
  "agentSessionId": "xwzdneft6emspe0f",
  "message": "Now also check stg_customers and post a summary to Slack."
}

Get an agent run

Fetches the current state of a DinoAI agent run.

Args

agentSessionId (String!): The session ID returned by triggerDinoaiAgentRun or sendDinoaiAgentMessage.

Returns

query DinoaiAgentRun($id: String!) {
  dinoaiAgentRun(agentSessionId: $id) {
    ok
    agentSessionId
    status
    messages {
      ts
      role
      content
    }
    childSessionIds
    workspaceUid
  }
}

{
  "id": "xwzdneft6emspe0f"
}

Example: curl

curl -X POST "$PARADIME_API_ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $PARADIME_API_KEY" \
  -H "X-API-SECRET: $PARADIME_API_SECRET" \
  -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"
      }
    }
  }'