> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finkkle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build and Publish Custom Plugins for Finkkle Spaces

> Create custom plugins that wrap your own APIs, webhooks, or scripts and make them available as tools inside Finkkle Spaces conversations.

The **Personal** segment of the Finkkle Spaces plugin catalog is designed for custom plugins. A custom plugin wraps your own API endpoint, webhook listener, or script behind a declared schema — making it available to Spaces as a callable tool in any conversation.

## What you can build

* **API wrapper** — expose a REST endpoint as a Spaces tool (e.g., query your internal knowledge base, fetch live pricing, trigger a workflow)
* **Webhook listener** — receive a Spaces-generated payload and act on it in your own system
* **Local script** — run a specific script in the Terminal Executor sandbox and surface its output

## Create a custom plugin

<Steps>
  <Step title="Describe the operation">
    Write a clear, plain-language description of what your plugin does. Spaces uses this to decide when the plugin is relevant:

    > *"Fetches the current inventory count for a given SKU from the warehouse API."*
  </Step>

  <Step title="Declare inputs and outputs">
    Define the plugin's schema:

    * **Required inputs** — fields the user must provide (e.g., `sku`, `date_range`)
    * **Optional inputs** — fields with defaults
    * **Output format** — what the plugin returns (JSON, Markdown, a file)
    * **Failure responses** — what Spaces should show when the plugin errors
  </Step>

  <Step title="Set permissions">
    Choose the smallest set of permissions your plugin needs:

    | Permission type | Use when                              |
    | --------------- | ------------------------------------- |
    | **Read**        | Fetching data without side effects    |
    | **Write**       | Creating or updating records          |
    | **Send**        | Dispatching messages or notifications |
    | **Account**     | Accessing a connected user account    |

    Default to read-only. Add write or send permissions only when necessary.
  </Step>

  <Step title="Test in the builder sandbox">
    Use the plugin builder sandbox to test with representative, non-sensitive data. Verify:

    * The input schema is correct
    * The output is understandable to someone other than the author
    * Error cases return actionable messages
    * The audit log entry is clear
  </Step>

  <Step title="Publish">
    Once the result and action log are clear and correct, publish the plugin to your personal catalog. It becomes available immediately in your Spaces conversations.
  </Step>
</Steps>

## Authentication

For plugins that call protected APIs, declare the authentication boundary in the schema:

* **API key** — store the key in the plugin configuration, not in conversation prompts
* **OAuth** — follow the standard OAuth authorization flow; Spaces handles token storage
* **No auth** — for public endpoints or local scripts

<Warning>
  Never include API keys, tokens, or credentials in conversation prompts or plugin descriptions. Store credentials in the plugin's secure configuration, not in the schema or description text.
</Warning>

## Best practices

* **Keep scope narrow** — one plugin per logical operation. Avoid building a multi-purpose plugin; split it into focused tools instead.
* **Test with realistic data** — use representative but non-sensitive samples in the sandbox.
* **Write clear error messages** — when the plugin fails, the message should tell the user exactly what to fix.
* **Use draft-only for side effects** — if your plugin creates or modifies records, default to draft mode so users approve before anything changes.
* **Document the output** — describe what a successful result looks like so Spaces and users both know what to expect.