Duckie API Overview

The Duckie API gives external systems access to your organization’s runs and configuration data. Use the REST API to export run history, analyze tool usage, sync agent configuration, or connect Duckie data to your internal reporting workflows. Use the MCP endpoint when an MCP client needs run tools or read/write access to core Duckie objects.

Base URL

https://app.useduckie.ai

REST API endpoints are under /api/v1. MCP clients use /api/mcp.

Available Resources

Resource	What you can read
Runs	Run summaries, run details, conversation messages, execution steps, evaluation attributes, and tool-call payloads after redaction and truncation
Tools	Duckie tools, app tools, custom tools, and MCP tools available to your organization
Agents	Agent configuration, instructions, linked tools, guidelines, guardrails, runbooks, workflows, categories, and attributes
Guidelines	Published guidelines and guideline section summaries
Guardrails	Escalation and restriction guardrails
Runbooks	Published, non-deleted runbooks
MCP endpoint	Run tools plus core object read/write tools

Request Example

curl "https://app.useduckie.ai/api/v1/runs?limit=25&status=completed" \
  -H "Authorization: Bearer dk_live_your_api_key"

List endpoints return data plus a pagination object:

{
  "data": [],
  "pagination": {
    "limit": 25,
    "next_cursor": null,
    "has_more": false
  }
}

Detail endpoints return one resource in data:

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "object": "run"
  }
}

Endpoint Summary

Method	Path	Description
`GET`	`/api/v1/runs`	List run summaries
`GET`	`/api/v1/runs/{run_id}`	Retrieve one run with conversation, steps, and evaluation data
`GET`	`/api/v1/runs/tool-options`	List historical tool names for run filtering
`GET`	`/api/v1/tools`	List tools
`GET`	`/api/v1/tools/{tool_id}`	Retrieve one tool
`GET`	`/api/v1/agents`	List agents
`GET`	`/api/v1/agents/{agent_id}`	Retrieve one agent
`GET`	`/api/v1/guidelines`	List published guidelines
`GET`	`/api/v1/guidelines/{guideline_id}`	Retrieve one guideline
`GET`	`/api/v1/guardrails`	List guardrails
`GET`	`/api/v1/guardrails/{guardrail_id}`	Retrieve one guardrail
`GET`	`/api/v1/runbooks`	List published runbooks
`GET`	`/api/v1/runbooks/{runbook_id}`	Retrieve one runbook
`POST`	`/api/mcp`	Call Duckie MCP tools through JSON-RPC

Next Steps

Authentication

Create an API key and send it with each request.

MCP Endpoint

Connect MCP clients to Duckie runs and core objects.

Pagination and Filtering

Page through large exports and narrow run lists.

Rate Limits

Plan around per-key, per-organization, and endpoint limits.

Error Responses

Handle common API failures consistently.

Guides

API Reference

Base URL

Available Resources

Request Example

Endpoint Summary

Next Steps

Authentication

MCP Endpoint

Pagination and Filtering

Rate Limits

Error Responses

​Base URL

​Available Resources

​Request Example

​Endpoint Summary

​Next Steps

Authentication

MCP Endpoint

Pagination and Filtering

Rate Limits

Error Responses

Base URL

Available Resources

Request Example

Endpoint Summary

Next Steps