Skip to main content
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

ResourceWhat you can read
RunsRun summaries, run details, conversation messages, execution steps, evaluation attributes, and tool-call payloads after redaction and truncation
ToolsDuckie tools, app tools, custom tools, and MCP tools available to your organization
AgentsAgent configuration, instructions, linked tools, guidelines, guardrails, runbooks, workflows, categories, and attributes
GuidelinesPublished guidelines and guideline section summaries
GuardrailsEscalation and restriction guardrails
RunbooksPublished, non-deleted runbooks
MCP endpointRun 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

MethodPathDescription
GET/api/v1/runsList run summaries
GET/api/v1/runs/{run_id}Retrieve one run with conversation, steps, and evaluation data
GET/api/v1/runs/tool-optionsList historical tool names for run filtering
GET/api/v1/toolsList tools
GET/api/v1/tools/{tool_id}Retrieve one tool
GET/api/v1/agentsList agents
GET/api/v1/agents/{agent_id}Retrieve one agent
GET/api/v1/guidelinesList published guidelines
GET/api/v1/guidelines/{guideline_id}Retrieve one guideline
GET/api/v1/guardrailsList guardrails
GET/api/v1/guardrails/{guardrail_id}Retrieve one guardrail
GET/api/v1/runbooksList published runbooks
GET/api/v1/runbooks/{runbook_id}Retrieve one runbook
POST/api/mcpCall 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.