DinoAI Programmable Agents API

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

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.

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
Returns

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

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

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.

{
  "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
Returns

agentSessionId (String!): The session ID of the running agent.message (String!): The follow-up message to send.

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

SendDinoAiAgentMessage

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

{
  "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
Returns

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

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

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.

{
  "id": "xwzdneft6emspe0f"
}

Example: curl

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"
      }
    }
  }'

​Trigger an agent run

​Send a follow-up message

​Get an agent run

Trigger an agent run

Send a follow-up message

Get an agent run