> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Duckie API Overview

> Export Duckie data and connect MCP clients

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

```text theme={null}
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

```bash theme={null}
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:

```json theme={null}
{
  "data": [],
  "pagination": {
    "limit": 25,
    "next_cursor": null,
    "has_more": false
  }
}
```

Detail endpoints return one resource in `data`:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Create an API key and send it with each request.
  </Card>

  <Card title="MCP Endpoint" icon="plug" href="/api/mcp">
    Connect MCP clients to Duckie runs and core objects.
  </Card>

  <Card title="Pagination and Filtering" icon="filter" href="/api/pagination-and-filtering">
    Page through large exports and narrow run lists.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api/rate-limits">
    Plan around per-key, per-organization, and endpoint limits.
  </Card>

  <Card title="Error Responses" icon="triangle-alert" href="/api/errors">
    Handle common API failures consistently.
  </Card>
</CardGroup>