---
title: "Upsert a custom toolkit"
method: POST
path: "/api/v3/custom/toolkits/upsert"
tags: ["Toolkits"]
---

# Upsert a custom toolkit

`POST /api/v3/custom/toolkits/upsert`

Experimental: custom toolkits are in pilot and this contract may change. Creates a custom toolkit for the project with the provided slug, or updates its display metadata (name, API key field copy) when the project already owns a toolkit with that slug. app_url and auth_schemes cannot be changed on an existing toolkit: re-sending them unchanged is a no-op, changing them returns 409 (delete and re-register the toolkit instead, which revokes its connections).

## Request body

- object
  - `slug` string, required — Unique slug identifier for the toolkit. Your slug will be prefixed with CUSTOM_ to avoid collision with composio managed toolkits. Spaces will be converted to underscores.
  - `toolkit_config` object, required
    - `name` string, required — Human readable name for your application
    - `app_url` string, uri, required — App URL for the toolkit. For MCP apps, please provide the MCP URL here
    - `logo_file` object — Square logo image (PNG or JPEG, 256-1024px, max 3MB) shown for this toolkit in the dashboard and on connect pages. Uploaded to Composio-hosted storage; defaults to the Composio logo when omitted.
      - `content` string, required — Base64-encoded image bytes, max 3MB decoded
      - `mime_type` 'image/png' | 'image/jpeg', required — Image MIME type of the encoded bytes
    - `auth_schemes` union[], required — Authentication schemes for the toolkit
      - union
        - object
          - `mode` 'NO_AUTH', required
        - object
          - `mode` 'API_KEY', required
          - `headers` object, required — Headers to be used for the API key authentication. Please replace your actual api key with {{generic_api_key}}
          - `api_key_field` object — End-user-facing copy for the API key input on the connect page
            - `display_name` string — Label shown to end users for the API key input on the connect page
            - `description` string — Help text shown to end users below the API key input on the connect page
        - object
          - `mode` 'DCR_OAUTH', required
          - `discovery_url` string, uri, required — URL to fetch the full auth scheme from, usually the /.well-known/oauth-authorization-server path of your MCP URL

## Response `200`

Successfully upserted toolkit

- object
  - `slug` string, required — Slug to be used with composio

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized - Invalid or missing admin credentials
- `404` — Not found - Toolkit not found
- `408` — Request timeout
- `409` — Conflict - app_url or auth_schemes differ from the registered toolkit; delete and re-register to change them
- `500` — Internal server error - Failed to sync toolkit

---

[API](https://skmtc.dev/composiohq/apis/composio-platform-api.md) · [All operations](https://skmtc.dev/composiohq/apis/composio-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/composiohq/composio-platform-api/revisions/368fb7851f42/schema)