---
title: "Create a plugin"
method: POST
path: "/v1/plugins"
tags: ["Plugins"]
---

# Create a plugin

`POST /v1/plugins`

Creates a new plugin with optional inline hooks

## Request body

- SchemasCreatePluginRequest
  - `description` string
  - `name` string, required
  - `plugin_type` 'webhook', required
  - `retry` SchemasCreateRetryConfigRequest
    - `backoff` 'fixed' | 'exponential'
    - `base_delay_ms` integer
    - `enabled` boolean
    - `max_attempts` integer
    - `retry_on` string[]
  - `status` 'inactive' | 'active'
  - `webhook_config` SchemasCreateWebhookConfigRequest
    - `auth` SchemasWebhookAuthRequest
      - `ca_cert` string
      - `client_cert` string
      - `client_key` string
      - `token` string
      - `type` 'bearer' | 'mtls' | 'none'
    - `endpoints` SchemasCreateWebhookEndpointsRequest, required
      - `access` SchemasWebhookEndpointRequest
        - `cache_enabled` boolean
        - `cache_ttl_ms` integer — 1s to 1 week
        - `failure_mode` 'fail_closed' | 'fail_open', required
        - `phase` 'before' | 'after', required
        - `priority` integer
        - `status` 'inactive' | 'active'
        - `timeout_ms` integer — 100ms to 2 minutes
        - `url` string, required
      - `post` SchemasWebhookEndpointRequest
        - `cache_enabled` boolean
        - `cache_ttl_ms` integer — 1s to 1 week
        - `failure_mode` 'fail_closed' | 'fail_open', required
        - `phase` 'before' | 'after', required
        - `priority` integer
        - `status` 'inactive' | 'active'
        - `timeout_ms` integer — 100ms to 2 minutes
        - `url` string, required
      - `pre` SchemasWebhookEndpointRequest
        - `cache_enabled` boolean
        - `cache_ttl_ms` integer — 1s to 1 week
        - `failure_mode` 'fail_closed' | 'fail_open', required
        - `phase` 'before' | 'after', required
        - `priority` integer
        - `status` 'inactive' | 'active'
        - `timeout_ms` integer — 100ms to 2 minutes
        - `url` string, required
    - `health_check_path` string

## Response `201`

Created

- SchemasCreatePluginResponse
  - `binding` SchemasBindingResponse
    - `id` string
    - `type` 'static' | 'tenant' | 'project' | 'account'
  - `created_at` string
  - `created_by` string
  - `description` string
  - `health_status` string
  - `hooks` SchemasHookResponse[]
    - `cache_enabled` boolean
    - `cache_ttl_ms` integer
    - `created_at` string
    - `failure_mode` 'fail_closed' | 'fail_open'
    - `hook_point` string
    - `id` string
    - `name` string
    - `phase` 'before' | 'after'
    - `plugin_id` string
    - `priority` integer
    - `status` 'inactive' | 'active'
    - `timeout_ms` integer
    - `updated_at` string
    - `version` integer
  - `id` string
  - `name` string
  - `plugin_type` string
  - `retry` SchemasRetryConfigResponse
    - `backoff` string
    - `base_delay_ms` integer
    - `enabled` boolean
    - `max_attempts` integer
    - `retry_on` string[]
  - `status` 'inactive' | 'active'
  - `updated_at` string
  - `updated_by` string
  - `version` integer
  - `webhook_config` SchemasWebhookConfigResponse
    - `auth` SchemasWebhookAuthResponse
      - `ca_cert` string
      - `client_cert_configured` boolean
      - `client_key_configured` boolean
      - `token` SchemasSecretResponse
        - `binding` 'static' | 'tenant' | 'project' | 'account'
        - `editable` boolean
        - `exists` boolean
        - `value` string
      - `type` string
    - `endpoints` SchemasWebhookEndpointsResponse
      - `access` SchemasWebhookEndpointResponse
        - `cache_enabled` boolean
        - `cache_ttl_ms` integer
        - `timeout_ms` integer
        - `url` string
      - `post` SchemasWebhookEndpointResponse
        - `cache_enabled` boolean
        - `cache_ttl_ms` integer
        - `timeout_ms` integer
        - `url` string
      - `pre` SchemasWebhookEndpointResponse
        - `cache_enabled` boolean
        - `cache_ttl_ms` integer
        - `timeout_ms` integer
        - `url` string
    - `health_check_path` string

## Other responses

- `400` — Bad Request
- `409` — Conflict
- `500` — Internal Server Error

## Changes

- **2026-02-18** `2a6c58164e9f` — 1 warning
  - removed the optional property `webhook_config/auth/token/hint` from the response with the `201` status
- **2026-02-11** `9f840d4f4997` — 5 info
  - the request property `webhook_config/auth/type` became optional
  - the request property `webhook_config/endpoints/access/priority` became optional
  - the request property `webhook_config/endpoints/post/priority` became optional
  - the request property `webhook_config/endpoints/pre/priority` became optional
  - …1 more
- **2026-02-06** `b0c6cc68de34` — 3 breaking, 14 info
  - the request property `webhook_config/endpoints/access/priority` became required
  - the request property `webhook_config/endpoints/post/priority` became required
  - the request property `webhook_config/endpoints/pre/priority` became required
  - added the new optional request property `webhook_config/endpoints/access/cache_enabled`
  - …13 more
- **2026-02-04** `d076f9130b9b` — 3 breaking, 9 info
  - the `webhook_config/endpoints/access` response's property type/format changed from `string`/`` to `object`/`` for status `201`
  - the `webhook_config/endpoints/post` response's property type/format changed from `string`/`` to `object`/`` for status `201`
  - the `webhook_config/endpoints/pre` response's property type/format changed from `string`/`` to `object`/`` for status `201`
  - added the new optional request property `webhook_config/endpoints/access/timeout_ms`
  - …8 more
- …earlier changes not shown

[Full history](https://skmtc.dev/arcadeai/apis/arcade-api/changes/v1/plugins/post.md)

---

[API](https://skmtc.dev/arcadeai/apis/arcade-api.md) · [All operations](https://skmtc.dev/arcadeai/apis/arcade-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/arcadeai/arcade-api/revisions/a509111298b2/schema)