> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-in-ai/17.latest/mcp/base-mcp/sdk/api-helpers.md).

# API Helpers

The SDK provides helper functions for executing Umbraco Management API calls with standardized error handling and response formatting. These helpers handle the repetitive parts of API communication so your tool handlers stay concise.

## When to Use Helpers

Use the built-in helpers for standard CRUD operations (roughly 80% of tools):

| Helper                          | Use Case                                                        |
| ------------------------------- | --------------------------------------------------------------- |
| `executeGetApiCall`             | GET single item                                                 |
| `executeGetItemsApiCall`        | GET collections or arrays                                       |
| `executeVoidApiCall`            | DELETE, PUT, or POST without response body                      |
| `executeVoidApiCallWithOptions` | Same as above with custom success message or extra status codes |

Go manual when you need:

* UUID generation for entity creation
* Response transformation or custom output
* Custom status handling (for example, 202 Accepted)
* Complex request building

## How Helpers Work

Each helper follows the same five steps:

1. Gets the configured API client via `getApiClient()`.
2. Executes your API call function, passing the client.
3. Validates the response is an `AxiosResponse` (warns if not).
4. Checks the HTTP status code: 200-299 is success, anything else is an error.
5. Returns an MCP-formatted `CallToolResult` with structured content on success, or throws `UmbracoApiError` on failure.

## CAPTURE\_RAW\_HTTP\_RESPONSE

You **must** pass this constant to every API call when using the helper functions.

```typescript
export const CAPTURE_RAW_HTTP_RESPONSE = {
  returnFullResponse: true,
  validateStatus: () => true,
} as const;
```

{% hint style="warning" %}
Without `CAPTURE_RAW_HTTP_RESPONSE`, Axios throws on 400+ errors instead of returning them. The helpers need the full `AxiosResponse` object to check status codes and extract ProblemDetails.
{% endhint %}

```typescript
// Correct - helpers receive AxiosResponse with status code
client.deleteDataTypeById(id, CAPTURE_RAW_HTTP_RESPONSE)

// Wrong - helpers receive undefined/void, status checking fails
client.deleteDataTypeById(id)
```

## Error Handling

API errors follow the RFC 7807 Problem Details format. The SDK provides two error classes:

* **`UmbracoApiError`** — wraps a ProblemDetails object for API-level errors (404, 409, and so on)
* **`ToolValidationError`** — for input validation failures before the API call is made

The `withErrorHandling` decorator catches both error types automatically and converts them to tool error results — you don't need to handle them yourself.

```typescript
import { UmbracoApiError, ToolValidationError } from "@umbraco-cms/mcp-server-sdk";

// API error — returned as a structured error to the LLM
throw new UmbracoApiError({
  status: 404,
  title: "Not Found",
  detail: "The data type was not found",
});

// Validation error — returned before making an API call
throw new ToolValidationError("The name field is required");
```

## HTTP Client

The SDK provides two HTTP client implementations depending on the transport:

* **Stdio transport** — Uses an Axios-based client (`UmbracoAxios`) with OAuth client credentials authentication, automatic token refresh, and self-signed certificate support. The API user credentials from your `.env` file are used.
* **Hosted transport** — Uses a fetch-based client provided by the [`@umbraco-cms/mcp-hosted`](/umbraco-in-ai/17.latest/mcp/base-mcp/hosted-mcp.md) package. The authenticated backoffice user's token is used.

The project template configures both transports for you. The API call helpers work with either client through the `configureApiClient` provider — your tool handlers do not need to know which transport is in use.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.umbraco.com/umbraco-in-ai/17.latest/mcp/base-mcp/sdk/api-helpers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.