# What Is the Purpose of the `api` Key in a Claude Plugin Manifest?

> Understand the purpose of the api key in Claude plugin manifests. Learn how it defines HTTP APIs for tool execution, endpoint configuration, authentication, and schema validation.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: deep-dive
- Published: 2026-09-01

---

**The `api` key in a Claude plugin manifest defines the HTTP API that the plugin calls when Claude executes its tools, acting as a single source of truth for base endpoint configuration, authentication handling, and schema validation.**

In the **anthropics/claude-plugins-community** repository, each plugin declares its external service integration through a manifest file. The `api` key sits at the top level of this manifest and governs how every tool in the plugin communicates with third-party services. Understanding this key is essential for building secure, maintainable, and portable Claude plugins.

## How the `api` Key Defines the Base Endpoint

The primary function of the `api` key is to specify a **base URL** that all tools in the plugin share. Individual tool definitions then declare only their relative paths, which Claude concatenates with this base.

In `plugins/*/.claude-plugin/manifest.json`, the structure looks like this:

```json
{
  "name": "weather-forecast",
  "description": "Fetches current weather data.",
  "api": {
    "url": "https://api.openweathermap.org/data/2.5"
  },
  "tools": [
    {
      "name": "getCurrentWeather",
      "path": "/weather",
      "method": "GET",
      "query": {
        "q": "{city}",
        "units": "metric"
      }
    }
  ]
}

```

When Claude executes `getCurrentWeather`, it automatically prefixes the tool's `path` (`/weather`) with the `api.url`, forming the complete request URL: `https://api.openweathermap.org/data/2.5/weather?q={city}&units=metric`.

This centralization means you can **change environments without editing individual tools**. A production manifest might use `https://api.example.com/v1` while a development manifest uses `https://dev.api.example.com/v1`—the tools remain identical.

## Authentication Configuration Through the `api` Key

The `api` key also enables **declarative authentication handling**. Rather than hardcoding credentials in tool definitions, you specify an `auth` object that Claude's runtime applies to every request using that API.

```json
{
  "api": {
    "url": "https://api.stripe.com/v1",
    "auth": {
      "type": "header",
      "headerName": "Authorization",
      "valueTemplate": "Bearer {secret}"
    }
  },
  "tools": [
    {
      "name": "listCustomers",
      "path": "/customers",
      "method": "GET"
    }
  ]
}

```

Here, Claude injects the user-supplied secret into the `Authorization` header for every request to `api.stripe.com`. The supported authentication patterns and their schemas are defined in `plugins/*/.claude-plugin/api-schema.json`, which validates that `auth` objects contain required fields like `type`, `headerName` (for header-based auth), or `keyName` (for query-parameter-based auth).

## Schema Validation of the `api` Object

Every `api` entry is validated against the **API schema** located at `plugins/*/.claude-plugin/api-schema.json`. This JSON Schema enforces structural integrity before a plugin is published, preventing runtime failures from malformed configurations.

The schema typically defines allowed fields:

- `url` (string, required): The base endpoint
- `auth` (object): Authentication configuration
- `timeout` (number): Request timeout in milliseconds
- `retry` (object): Retry policy for failed requests

Validation occurs during the plugin packaging process, ensuring that only well-formed `api` configurations reach production.

## File Structure and Key Locations

The following files work together to implement the `api` key functionality:

- `plugins/*/.claude-plugin/manifest.json` — Contains the top-level `api` definition
- `plugins/*/.claude-plugin/api-schema.json` — Validates the `api` object structure
- `plugins/*/.claude-plugin/tools/*.json` — Individual tool specifications that reference the shared `api` configuration
- [`docs/plugin-manifest.md`](https://github.com/anthropics/claude-plugins-community/blob/main/docs/plugin-manifest.md) — Documentation describing manifest fields and their purposes

## Summary

- The **`api` key** in a Claude plugin manifest establishes the base URL for all HTTP requests made by that plugin's tools.
- It supports **centralized authentication** configuration, keeping credentials out of individual tool definitions.
- The **`api`-schema.json** file validates `api` objects against a strict JSON Schema, catching configuration errors early.
- Environment portability is simplified: change the `api.url` value to switch between staging, development, and production without modifying tool code.

## Frequently Asked Questions

### What happens if I omit the `api` key from my plugin manifest?

A plugin manifest without an `api` key cannot define HTTP-based tools. The Claude runtime requires this key to resolve request URLs. If your plugin only provides static resources or computation without external API calls, you may not need it—but such plugins are uncommon in the **anthropics/claude-plugins-community** ecosystem.

### Can a single plugin define multiple `api` endpoints?

No. The manifest structure supports exactly one top-level `api` object. If your plugin needs to communicate with multiple distinct services, you must either create separate plugins or route all requests through a single intermediary service that handles the distribution.

### How does Claude handle `api` authentication secrets securely?

Claude never stores secrets in the manifest itself. The `auth` configuration in `api.auth` uses templates like `{secret}` that reference credentials supplied by the end user at runtime. These values are injected into requests at execution time and are not persisted in plugin files or logs, as specified in the authentication patterns documented in [`docs/plugin-manifest.md`](https://github.com/anthropics/claude-plugins-community/blob/main/docs/plugin-manifest.md).

### Where can I find examples of production `api` configurations?

Browse the `plugins/` directory in the **anthropics/claude-plugins-community** repository. Each subdirectory containing a [`.claude-plugin/manifest.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/manifest.json) demonstrates real-world `api` usage patterns, including variations for OAuth, API keys, and custom header authentication.