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

# Upsert a custom toolkit

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

## Request

- Base URL: `https://backend.composio.dev`
- URL: `https://backend.composio.dev/api/v3.1/custom/toolkits/upsert`
- Auth: one of:
  - API key in header `x-api-key`
  - API key in header `x-user-api-key`

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. A toolkit created here is shared with every user in the project; an existing toolkit keeps its access. 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: Display name of the toolkit
    - `app_url` string, uri, required: MCP server URL. Must use https.
    - `logo_file` object: Square PNG or JPEG logo, 256-1024px, max 3MB. Defaults to the Model Context Protocol logo.
      - `content` string, required: Base64-encoded image, max 3MB decoded
      - `mime_type` 'image/png' | 'image/jpeg', required: Image MIME type
    - `auth_schemes` union[], required: How users authenticate to the MCP server
      - union
        - object
          - `mode` 'NO_AUTH', required
        - object
          - `mode` 'API_KEY', required
          - `headers` object, required: Headers sent to the MCP server. Use {{generic_api_key}} where the API key goes.
          - `api_key_field` object: Label and help text for the API key input on the connect page
            - `display_name` string: Label for the API key input
            - `description` string: Help text below the API key input
          - `additional_fields` object: Additional values each user enters when connecting. Reference each field in a header, for example X-Org-Id: {{generic_id}}. Use display_name for the user-facing label. Every user must supply each declared field. Values are not secret.
            - `generic_id` object, required
              - …
        - object
          - `mode` 'DCR_OAUTH', required
          - `discovery_url` string, uri, required: OAuth authorization server metadata URL, for example https://<auth server host>/.well-known/oauth-authorization-server. Use the URL your authorization server publishes; it can be on a different host from the MCP server or include a path.

## 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
- `429`: Too many requests - The upstream service is rate limiting the request; retry after a short backoff
- `500`: Internal server error - Failed to sync toolkit

## Changes

- **2026-10-16** `98956f31abf3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/composiohq/apis/composio-platform-api-v3-1/changes/api/v3.1/custom/toolkits/upsert/post.md)

---

[API](https://skmtc.dev/composiohq/apis/composio-platform-api-v3-1.md) - [All operations](https://skmtc.dev/composiohq/apis/composio-platform-api-v3-1/llms.txt) - [OpenAPI document](https://skmtc.dev/composiohq/apis/composio-platform-api-v3-1/revisions/4bd56a0836f8?raw)