Paperclip

https://docs.paperclip.ing
Admin
Paperclip is an agent orchestration platform that manages AI agents, handles scheduling, execution...
Tokens:682,716
Snippets:4,718
Trust Score:6.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### POST /api/companies/{companyId}/tools/examples/{id}/install

Source: https://docs.paperclip.ing/reference/api/tool-gateway

Installs a prebuilt example setup into the company.

```APIDOC
## POST /api/companies/{companyId}/tools/examples/{id}/install

### Description
Installs a prebuilt example setup into the company.

### Method
POST

### Endpoint
/api/companies/{companyId}/tools/examples/{id}/install

### Parameters
#### Path Parameters
- **companyId** (string) - Required - The unique identifier of the company.
- **id** (string) - Required - The identifier of the example to install.

### Response
#### Success Response (200)
- **status** (string) - Installation status.

#### Response Example
{
  "status": "installed"
}
```

--------------------------------

### Example endpoints: list, install, smoke

Source: https://docs.paperclip.ing/reference/api/tool-gateway

Use these endpoints to work with prebuilt example setups. The list route returns available examples, install installs one, and smoke runs a smoke test in place.

```http
GET  /api/companies/{companyId}/tools/examples
POST /api/companies/{companyId}/tools/examples/{id}/install
POST /api/companies/{companyId}/tools/examples/{id}/smoke
```

--------------------------------

### GET /api/companies/{companyId}/tools/examples

Source: https://docs.paperclip.ing/reference/api/tool-gateway

Retrieves a list of prebuilt, working example setups that can be installed and smoke-tested.

```APIDOC
## GET /api/companies/{companyId}/tools/examples

### Description
Retrieves a list of prebuilt, working example setups that can be installed and smoke-tested.

### Method
GET

### Endpoint
/api/companies/{companyId}/tools/examples

### Parameters
#### Path Parameters
- **companyId** (string) - Required - The unique identifier of the company.

### Response
#### Success Response (200)
- **examples** (array) - List of available examples.

#### Response Example
{
  "examples": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}
```

--------------------------------

### paperclipai onboard: run interactive setup

Source: https://docs.paperclip.ing/reference/cli/setup-commands

Run the interactive first-run setup wizard. Use --yes to accept Quickstart defaults non-interactively, --run to start the server immediately after saving the config, and --bind lan to set the Quickstart reachability preset to LAN. The wizard writes the config, provisions the PAPERCLIP_AGENT_JWT_SECRET into the adjacent .env file, and creates the local secrets key file.

```sh
paperclipai onboard
paperclipai onboard --yes
paperclipai onboard --run
paperclipai onboard --bind lan
```

--------------------------------

### List example plugins with paperclipai plugin examples

Source: https://docs.paperclip.ing/reference/cli/plugin

Lists the example plugins bundled with the app. Each entry prints its display name, plugin key, description, and a ready-to-run local install command. Copy the printed `paperclipai plugin install <local-path>` line to install one straight from the bundle.

```sh
paperclipai plugin examples
paperclipai plugin examples --json
```

--------------------------------

### Onboard with flags: --yes, --run, --bind lan

Source: https://docs.paperclip.ing/reference/cli/installation

Shows non-interactive onboarding options. --yes accepts Quickstart defaults and starts immediately; --run saves config and starts right away; --bind lan applies a LAN reachability preset. In an interactive terminal, onboarding also asks about installing a background service; --install-service and --no-install-service control that without prompting.

```sh
# Non-interactive Quickstart that boots immediately
paperclipai onboard --yes

# Save the config and start, but keep interactive prompts
paperclipai onboard --run

# Quickstart bound to the LAN instead of loopback
paperclipai onboard --bind lan
```

--------------------------------

### Example JSON body for adapter installation

Source: https://docs.paperclip.ing/reference/adapters/external-adapters

Example request body for installing an external adapter. The `packageName` field is required; `version` and `isLocalPath` are optional. Set `isLocalPath` to `true` for a local checkout.

```json
{
  "packageName": "@henkey/hermes-paperclip-adapter",
  "version": "latest",
  "isLocalPath": false
}
```

--------------------------------

### Browse bundled example plugins with paperclipai plugin examples

Source: https://docs.paperclip.ing/how-to/develop-a-plugin-locally

Lists bundled example plugins. Each row includes a ready-to-run `paperclipai plugin install <path>` line, useful for copying a manifest shape or surfacing a contribution.

```bash
paperclipai plugin examples
```

--------------------------------

### Start Paperclip with Docker Compose quickstart

Source: https://docs.paperclip.ing/reference/deploy/docker

Runs the compose-based quickstart, which is the recommended path. Opens the app at http://localhost:3100 with defaults: host port 3100 and data directory ./data/docker-paperclip.

```sh
docker compose -f docker/docker-compose.quickstart.yml up --build
```

--------------------------------

### Start the server with pnpm install and pnpm dev

Source: https://docs.paperclip.ing/reference/deploy/local-development

Installs dependencies and starts the API server at http://localhost:3100 with the UI in dev middleware mode. The first start automatically uses embedded PostgreSQL if DATABASE_URL is unset.

```sh
pnpm install
pnpm dev
```

--------------------------------

### Run onboarding wizard: paperclipai onboard

Source: https://docs.paperclip.ing/reference/cli/installation

Runs the interactive first-run wizard. It writes a config file and local key material, then offers to start Paperclip. Use for new local installs or rebuilding config from guided prompts. It also ensures the agent JWT secret and secrets key file exist, and prints the resolved configuration and next commands when finished.

```sh
paperclipai onboard
```

--------------------------------

### Start Runtime Service (cURL, JavaScript, Python)

Source: https://docs.paperclip.ing/reference/api/goals-and-projects

Starts a runtime service for a workspace. The cURL, JavaScript, and Python examples are equivalent alternatives for the same endpoint. Requires a local path (`cwd`) and workspace runtime configuration.

```bash
curl -X POST "http://localhost:3100/api/projects/{projectId}/workspaces/{workspaceId}/runtime-services/start" \
  -H "Authorization: Bearer <token>"
```

```javascript
await fetch(
  `http://localhost:3100/api/projects/${projectId}/workspaces/${workspaceId}/runtime-services/start`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${token}` },
  },
);
```

```python
import requests

requests.post(
    f"http://localhost:3100/api/projects/{project_id}/workspaces/{workspace_id}/runtime-services/start",
    headers={"Authorization": f"Bearer {token}"},
)
```

--------------------------------

### Install Paperclip and register as a background service

Source: https://docs.paperclip.ing/guides/getting-started/installation

The first command installs Paperclip properly and offers to add it to your shell's PATH. The second registers Paperclip as a background service that starts at login and restarts if it crashes. No administrator rights are needed.

```bash
npx paperclipai install
```

```bash
paperclipai service install
```

--------------------------------

### GET /api/plugins/examples

Source: https://docs.paperclip.ing/reference/api/plugins

Lists the bundled plugins discovered in the current checkout (reference examples and vendored first-party plugins).

```APIDOC
## GET /api/plugins/examples

### Description
Lists the bundled plugins discovered in the current checkout (reference examples and vendored first-party plugins). The server scans the bundled packages on disk for plugin manifests, so the result reflects whatever your checkout actually contains. The result is cached after the first scan.

### Method
GET

### Endpoint
/api/plugins/examples

### Response
#### Success Response (200)
- **packageName** (string) - The package name of the plugin.
- **pluginKey** (string) - The plugin key.
- **displayName** (string) - The display name of the plugin.
- **description** (string) - Description of the plugin.
- **localPath** (string) - Path to the plugin in the checkout.
- **tag** (string) - `example` for reference plugins, `first-party` for vendored plugins.
- **experimental** (boolean) - `true` for first-party plugins that aren't production-ready yet.

#### Response Example
```json
{
  "packageName": "@paperclipai/plugin-llm-wiki",
  "pluginKey": "llm-wiki",
  "displayName": "LLM Wiki",
  "description": "...",
  "localPath": "packages/plugins/...",
  "tag": "first-party",
  "experimental": true
}
```
```

--------------------------------

### Already running: connect and list companies

Source: https://docs.paperclip.ing/reference/cli/overview

Skip onboarding and connect to an already-running instance, then list companies.

```sh
paperclipai connect
paperclipai company list
```

--------------------------------

### Move from npx to managed install

Source: https://docs.paperclip.ing/how-to/update-paperclip

For an npx-based setup, update reports there is nothing to install and directs you to a managed install. Run the install command first, then use update thereafter.

```bash
npx paperclipai install     # move to a managed install
paperclipai update          # from then on, this works
```

--------------------------------

### Run Paperclip onboarding with --yes

Source: https://docs.paperclip.ing/guides/power/terminal-setup

Runs the one-command onboarding that downloads Paperclip, creates the config directory, initialises the database, and starts the server. The --yes flag accepts all defaults. The displayed output shows the expected success messages.

```bash
npx paperclipai onboard --yes
```

```text
✓ Created config at ~/.paperclip/instances/default/config.json
✓ Initialised database
✓ Server running at http://localhost:3100
→ Opening Paperclip in your browser...
```

--------------------------------

### Install Node.js 24+ and git

Source: https://docs.paperclip.ing/guides/getting-started/installation

Installs Node.js 24+ and git from NodeSource. The setup script is fetched and executed with sudo, then nodejs, git, and ca-certificates are installed via apt.

```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs git ca-certificates
```

--------------------------------

### GET /api/plugins

Source: https://docs.paperclip.ing/reference/api/plugins

Lists installed plugins on this instance.

```APIDOC
## GET /api/plugins

### Description
Lists installed plugins on this instance.

### Method
GET

### Endpoint
/api/plugins

### Response
#### Success Response (200)
- **plugins** (array) - List of installed plugins.

#### Response Example
```json
[
  {
    "packageName": "@paperclipai/plugin-llm-wiki",
    "pluginKey": "llm-wiki",
    "displayName": "LLM Wiki",
    "description": "...",
    "localPath": "packages/plugins/...",
    "tag": "first-party",
    "experimental": true
  }
]
```
```

--------------------------------

### Run Paperclip onboarding

Source: https://docs.paperclip.ing/guides/getting-started/installation

Runs the onboarding command that downloads Paperclip, creates config at ~/.paperclip/, initializes embedded DB, and starts server at http://localhost:3100. Must be run as a normal user, not root or with sudo. The --yes flag accepts all defaults.

```bash
npx paperclipai onboard --yes
```

--------------------------------

### GET /api/decision-training/{id}

Source: https://docs.paperclip.ing/reference/api/decision-training

Get a single decision training example by UUID, including full snapshot, notes, and notes history.

```APIDOC
## GET /api/decision-training/{id}

### Description
Return one example by UUID, including its full snapshot, notes, and notesHistory. Returns 404 if the id is not a UUID or the example belongs to a company you cannot access.

### Method
GET

### Endpoint
/api/decision-training/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The example's UUID.

### Response
#### Success Response (200)
- **id** (string) - The example's UUID.
- **companyId** (string) - Owning company.
- **sourceKind** (string) - The source kind.
- **sourceId** (string) - The source identifier.
- **issueId** (string) - The issue identifier.
- **cutoffAt** (string) - The moment the snapshot was frozen.
- **notes** (string) - The current note text.
- **notesHistory** (array) - Prior note versions, each `{ author, at, body }`.
- **decisionOutcome** (string) - The recorded outcome, or null if pending.
- **retentionPolicy** (string) - The retention policy applied.
- **snapshot** (object) - The frozen state.
- **createdByUserId** (string) - The human who captured it.
- **createdAt** (string) - Creation timestamp.
- **updatedAt** (string) - Update timestamp.

#### Error Response (404)
- **error** (string) - Error message.

### Response Example
{
  "id": "...",
  "companyId": "...",
  "sourceKind": "...",
  "sourceId": "...",
  "issueId": "...",
  "cutoffAt": "...",
  "notes": "...",
  "notesHistory": [ { "author": "...", "at": "...", "body": "..." } ],
  "decisionOutcome": "...",
  "retentionPolicy": "scrub_deleted_comments_v1",
  "snapshot": {},
  "createdByUserId": "...",
  "createdAt": "...",
  "updatedAt": "..."
}
```

--------------------------------

### Run Paperclip onboarding command

Source: https://docs.paperclip.ing/reference/deploy/overview

Starts the onboarding process for Paperclip. Use this when you are just trying Paperclip for the first time.

```sh
pnpm paperclipai onboard
```

--------------------------------

### GET /api/plugins/:pluginId

Source: https://docs.paperclip.ing/reference/api/plugins

Reads the installed plugin record.

```APIDOC
## GET /api/plugins/:pluginId

### Description
Reads the installed plugin record.

### Method
GET

### Endpoint
/api/plugins/:pluginId

### Parameters
#### Path Parameters
- **pluginId** (string) - Required - The identifier of the plugin.

### Response
#### Success Response (200)
Returns the plugin record.

#### Response Example
{
  "id": "plugin-id",
  "name": "plugin-name",
  "version": "1.0.0"
}
```

--------------------------------

### Get a decision-training example by ID

Source: https://docs.paperclip.ing/reference/api/decision-training

Fetches a single decision-training example by UUID. Returns full snapshot, notes, and notesHistory. Returns 404 Not Found with a generic error if the id is invalid or the example is not accessible.

```http
GET /api/decision-training/{id}
```

--------------------------------

### GET /api/companies/{companyId}/skills

Source: https://docs.paperclip.ing/how-to/write-a-company-skill

Lists all skills installed at the company level. Use this to verify a skill installation and retrieve its `key` and `id` for assignment to agents.

```APIDOC
## GET /api/companies/{companyId}/skills

### Description
Lists all skills installed at the company level. Use this to verify a skill installation and retrieve its `key` and `id` for assignment to agents.

### Method
GET

### Endpoint
/api/companies/{companyId}/skills

### Parameters
#### Path Parameters
- **companyId** (string) - Required - The unique identifier of the company.

### Request Example
```bash
curl "$PAPERCLIP_API_URL/api/companies/$COMPANY_ID/skills" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
```

### Response
#### Success Response (200)
- **skills[]** (array) - List of skills, each containing `slug`, `key`, and `id`.

#### Response Example
```json
{
  "skills": [
    {
      "slug": "release-note-writer",
      "key": "local/8a31d29e1c/release-note-writer",
      "id": "skill_123"
    }
  ]
}
```
```

--------------------------------

### Preview a catalog install with cURL, JavaScript, and Python

Source: https://docs.paperclip.ing/reference/api/teams-catalog

Send a POST request to the preview endpoint with a target manager slug and collision strategy. The response is a plan object that reports what would be created, required skills, and any warnings or errors. The endpoint checks company access before running the preview.

```bash
curl -X POST "http://localhost:3100/api/companies/company-1/teams/catalog/core-exec-team/preview" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "targetManagerSlug": "cto",
    "collisionStrategy": "rename"
  }'
```

```javascript
const res = await fetch(
  "http://localhost:3100/api/companies/company-1/teams/catalog/core-exec-team/preview",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      targetManagerSlug: "cto",
      collisionStrategy: "rename",
    }),
  },
);
const plan = await res.json();
```

```python
import requests

res = requests.post(
    "http://localhost:3100/api/companies/company-1/teams/catalog/core-exec-team/preview",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "targetManagerSlug": "cto",
        "collisionStrategy": "rename",
    },
)
plan = res.json()
```

--------------------------------

### Preview a team install

Source: https://docs.paperclip.ing/reference/cli/teams

Previews an install without writing anything. Requires a company context. The second example shows using --target-manager-slug and --collision-strategy.

```sh
paperclipai teams preview core-exec-team --company-id <company-id>
paperclipai teams preview product-engineering \
  --target-manager-slug cto \
  --collision-strategy rename \
  --company-id <company-id>
```

--------------------------------

### Bootstrap local instance: paperclipai onboard and run

Source: https://docs.paperclip.ing/reference/cli/installation

Bootstraps a local instance from an empty machine. onboard writes the instance config; run validates it and starts the server. If no config exists and you are in an interactive terminal, run calls onboarding automatically.

```sh
paperclipai onboard
paperclipai run
```

--------------------------------

### Export examples with GET /api/companies/{companyId}/decision-training/export.jsonl

Source: https://docs.paperclip.ing/reference/api/decision-training

Exports all decision training examples as newline-delimited JSON. Returns the same set and order as the list route, newest first. Applies no filters.

```http
GET /api/companies/{companyId}/decision-training/export.jsonl
```

--------------------------------

### POST /api/adapters/install

Source: https://docs.paperclip.ing/reference/api/adapters

Installs an external adapter package on the instance. Used by the Adapter Manager UI and the wiki CLI workflow.

```APIDOC
## POST /api/adapters/install

### Description
Installs an external adapter package on the instance. Used by the Adapter Manager UI and the wiki CLI workflow.

### Method
POST

### Endpoint
/api/adapters/install

### Parameters
None

### Response
#### Success Response (200)
- Success confirmation (object) - Installation result.
```

--------------------------------

### One-command bootstrap with pnpm paperclipai run

Source: https://docs.paperclip.ing/reference/deploy/local-development

Sets up and starts Paperclip in one step. Auto-onboards if no config exists, runs paperclipai doctor with repair enabled, and starts the server once checks pass.

```sh
pnpm paperclipai run
```
Tokens:
Raw