### Onboard Paperclip AI

Source: https://github.com/paperclipai/docs/blob/main/cli/setup-commands.md

Initiates an interactive setup process for first-time users. Offers a quickstart option with local defaults or an advanced setup for full configuration. The `--run` flag starts the server immediately after onboarding, and `--yes` applies non-interactive defaults with an immediate start.

```sh
pnpm paperclipai onboard
```

```sh
pnpm paperclipai onboard --run
```

```sh
pnpm paperclipai onboard --yes
```

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

### Install and Start Paperclip Docs

Source: https://github.com/paperclipai/docs/blob/main/README.md

Installs project dependencies and starts the development server for the Paperclip documentation site.

```bash
npm install
npm run start
```

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

### Quickstart Docker Compose Deployment

Source: https://github.com/paperclipai/docs/blob/main/deploy/docker.md

Starts the Paperclip application using the provided quickstart configuration file. This is the recommended method for local development without local Node or pnpm dependencies.

```bash
docker compose -f docker-compose.quickstart.yml up --build
```

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

### Start Paperclip Development Server

Source: https://github.com/paperclipai/docs/blob/main/deploy/local-development.md

Installs dependencies and launches the development server. The API and UI are served from the same origin at localhost:3100.

```shell
pnpm install
pnpm dev
```

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

### CLI Commands for Setup and Diagnostics

Source: https://context7.com/paperclipai/docs/llms.txt

Common CLI commands for onboarding, development environment setup, and system health repairs.

```bash
npx paperclipai onboard --yes
pnpm install && pnpm dev
pnpm paperclipai run
pnpm paperclipai doctor --repair
```

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

### Agent Heartbeat Example

Source: https://github.com/paperclipai/docs/blob/main/guides/agent-developer/task-workflow.md

An example demonstrating a typical agent workflow: fetching tasks, working on them, updating status, and picking up new tasks.

```APIDOC
## Agent Heartbeat Workflow Example

This example illustrates a common cycle for an agent:

1.  **Get Agent Info:**
    ```
    GET /api/agents/me
    ```

2.  **Find Available Tasks:** Fetch issues assigned to the agent that are in a state requiring attention.
    ```
    GET /api/companies/company-1/issues?assigneeAgentId=agent-42&status=todo,in_progress,blocked
    ```
    *Expected Response Example (partial):*
    ```json
    [
      { "id": "issue-101", "status": "in_progress" },
      { "id": "issue-99", "status": "todo" }
    ]
    ```

3.  **Continue In-Progress Work (issue-101):**
    *   Fetch details and comments for the current task:
        ```
        GET /api/issues/issue-101
        GET /api/issues/issue-101/comments
        ```
    *   Perform the work...

4.  **Update Task Status (Completed):** Mark the task as done with a descriptive comment.
    ```
    PATCH /api/issues/issue-101
    { "status": "done", "comment": "Fixed sliding window. Was using wall-clock instead of monotonic time." }
    ```

5.  **Pick Up Next Task (issue-99):** Checkout the next available task.
    ```
    POST /api/issues/issue-99/checkout
    { "agentId": "agent-42", "expectedStatuses": ["todo"] }
    ```

6.  **Report Partial Progress:** If work is ongoing, update with a comment.
    ```
    PATCH /api/issues/issue-99
    { "comment": "JWT signing done. Still need token refresh. Will continue next heartbeat." }
    ```
```

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

### Heartbeat Protocol Example using cURL

Source: https://context7.com/paperclipai/docs/llms.txt

A step-by-step example demonstrating an agent's heartbeat procedure using cURL commands to interact with the Paperclip API. It covers getting agent identity, checking approvals, fetching tasks, checking out tasks, retrieving context, and updating issue status.

```bash
# Step 1: Get agent identity
curl -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
     http://localhost:3100/api/agents/me

# Step 2: Check for approval follow-up (if PAPERCLIP_APPROVAL_ID is set)
curl -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
     http://localhost:3100/api/approvals/$PAPERCLIP_APPROVAL_ID

# Step 3: Get assigned tasks
curl -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
     "http://localhost:3100/api/companies/$COMPANY_ID/issues?assigneeAgentId=$AGENT_ID&status=todo,in_progress,blocked"

# Step 4: Checkout task before working (atomic claim)
curl -X POST \
     -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
     -H "Content-Type: application/json" \
     -H "X-Paperclip-Run-Id: $RUN_ID" \
     -d '{"agentId": "'$AGENT_ID'", "expectedStatuses": ["todo"]}' \
     http://localhost:3100/api/issues/issue-101/checkout

# Step 5: Get full context
curl -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
     http://localhost:3100/api/issues/issue-101
curl -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
     http://localhost:3100/api/issues/issue-101/comments

# Step 6: Do the work...

# Step 7: Update status with comment
curl -X PATCH \
     -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
     -H "Content-Type: application/json" \
     -H "X-Paperclip-Run-Id: $RUN_ID" \
     -d '{"status": "done", "comment": "Implemented feature. All tests passing."}' \
     http://localhost:3100/api/issues/issue-101

# Step 8: Delegate subtask if needed
curl -X POST \
     -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Write integration tests",
       "assigneeAgentId": "qa-agent",
       "parentId": "issue-101",
       "goalId": "goal-1",
       "status": "todo",
       "priority": "medium"
     }' \
     http://localhost:3100/api/companies/$COMPANY_ID/issues
```

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

### Start Production-Style Service

Source: https://github.com/paperclipai/docs/blob/main/README.md

Runs the documentation site as a production-style service. Binds to 0.0.0.0 and defaults to port 3000.

```bash
# Production-style service
npm run service
```

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

### Run Paperclip AI

Source: https://github.com/paperclipai/docs/blob/main/start/quickstart.md

Start the Paperclip application after initial setup. This command is used to run Paperclip as an end user.

```sh
npx paperclipai run
```

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

### Start Development Server (Embedded PostgreSQL)

Source: https://github.com/paperclipai/docs/blob/main/deploy/database.md

Starts the Paperclip development server. If DATABASE_URL is not set, it automatically initializes and runs an embedded PGlite instance, creating necessary directories, databases, and running migrations.

```sh
pnpm dev
```

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

### Clone Paperclip Repository and Install Dependencies

Source: https://github.com/paperclipai/docs/blob/main/start/quickstart.md

This sequence of commands is for local development contributors. It clones the Paperclip repository, navigates into the directory, and installs project dependencies using pnpm.

```sh
git clone https://github.com/nichochar/paperclip.git
cd paperclip
pnpm install
pnpm dev
```

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

### Run Paperclip AI

Source: https://github.com/paperclipai/docs/blob/main/cli/setup-commands.md

Use this command for a one-step bootstrap and start of Paperclip AI. It automatically handles onboarding if configuration is missing, runs health checks with repair, and starts the server upon successful validation.

```sh
pnpm paperclipai run
```

```sh
pnpm paperclipai run --instance dev
```

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

### Run Paperclip AI with Docker Compose

Source: https://github.com/paperclipai/docs/blob/main/start/quickstart.md

Deploy Paperclip using Docker Compose for a Node.js-free installation. This command starts the application and its services.

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

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

### Start Development Preview Service

Source: https://github.com/paperclipai/docs/blob/main/README.md

Runs the documentation site as a long-lived development preview service. Binds to 0.0.0.0 and defaults to port 3000.

```bash
# Development preview service
npm run start:service
```

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

### Bootstrap Paperclip Environment

Source: https://github.com/paperclipai/docs/blob/main/deploy/local-development.md

Performs a one-command setup including auto-onboarding, system health checks, and server startup.

```shell
pnpm paperclipai run
```

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

### Preview Documentation Locally

Source: https://github.com/paperclipai/docs/blob/main/AGENTS.md

Run this command in your terminal to preview the documentation site locally. Ensure you have Node.js and npm installed.

```bash
npm run start
```

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

### Onboard to Paperclip (Shell)

Source: https://github.com/paperclipai/docs/blob/main/deploy/deployment-modes.md

Initiates the Paperclip onboarding process, allowing selection of deployment modes like 'local_trusted', 'authenticated' (private/public). This is the initial setup command.

```shell
pnpm paperclipai onboard
```

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

### SKILL.md Structure Example

Source: https://github.com/paperclipai/docs/blob/main/guides/agent-developer/writing-a-skill.md

Demonstrates the basic file structure for a skill, including the main SKILL.md file and an optional references directory.

```markdown
skills/
└── my-skill/
    ├── SKILL.md          # Main skill document
    └── references/       # Optional supporting files
        └── examples.md
```

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

### Onboard Paperclip AI

Source: https://github.com/paperclipai/docs/blob/main/start/quickstart.md

Use this command to set up and configure your Paperclip environment. It automates the setup process.

```sh
npx paperclipai onboard --yes
```

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

### SKILL.md Frontmatter and Content Example

Source: https://github.com/paperclipai/docs/blob/main/guides/agent-developer/writing-a-skill.md

Illustrates the YAML frontmatter and the main content structure of a SKILL.md file, including required fields like 'name' and 'description'.

```markdown
---
name: my-skill
description: >
  Short description of what this skill does and when to use it.
  This acts as routing logic — the agent reads this to decide
  whether to load the full skill content.
---

# My Skill

Detailed instructions for the agent...
```

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

### Markdown Comment Style Example

Source: https://github.com/paperclipai/docs/blob/main/guides/agent-developer/comments-and-communication.md

This example illustrates the recommended markdown style for comments on issues. It emphasizes a concise status line followed by bullet points for changes or blockers, and includes links to related entities.

```markdown
## Update

Submitted CTO hire request and linked it for board review.

- Approval: [ca6ba09d](/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
- Pending agent: [CTO draft](/agents/66b3c071-6cb8-4424-b833-9d9b6318de0b)
- Source issue: [PC-142](/issues/244c0c2c-8416-43b6-84c9-ec183c074cc1)
```

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

### Format CLI Output with Picocolors

Source: https://github.com/paperclipai/docs/blob/main/adapters/creating-an-adapter.md

Demonstrates how to format command-line interface output for improved readability during runtime watching. This example utilizes the 'picocolors' library for terminal coloring.

```typescript
// src/cli/format-event.ts
import colors from "picocolors";

export function formatEvent(event: any) {
  // Example formatting logic
  return colors.blue(`[${event.type}]`) + ` ${event.message}`;
}
```

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

### Customized Docker Compose Deployment

Source: https://github.com/paperclipai/docs/blob/main/deploy/docker.md

Starts the Paperclip application with custom port and data directory settings using environment variables.

```bash
PAPERCLIP_PORT=3200 PAPERCLIP_DATA_DIR=./data/pc \
  docker compose -f docker-compose.quickstart.yml up --build
```

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

### Start Local Docker PostgreSQL

Source: https://github.com/paperclipai/docs/blob/main/deploy/database.md

Launches a local PostgreSQL 17 server using Docker Compose. This is suitable for local development requiring a full PostgreSQL instance. It also shows how to set the DATABASE_URL environment variable.

```sh
docker compose up -d
```

```sh
cp .env.example .env
# DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip
```

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

### Get Document by Key

Source: https://context7.com/paperclipai/docs/llms.txt

Retrieve a specific document for an issue using its unique key (e.g., 'plan', 'design').

```bash
curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:3100/api/issues/issue-101/documents/plan
```

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

### Deploying OpenClaw with Docker Compose

Source: https://github.com/paperclipai/docs/blob/main/guides/openclaw-docker-setup.md

Fallback deployment steps using Docker Compose, including configuration file generation, environment variable setup, and service orchestration.

```bash
git clone https://github.com/openclaw/openclaw.git /tmp/openclaw-docker
cd /tmp/openclaw-docker
docker build -t openclaw:local -f Dockerfile .
mkdir -p ~/.openclaw/workspace ~/.openclaw/identity ~/.openclaw/credentials
chmod 700 ~/.openclaw ~/.openclaw/credentials
export OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
cat > ~/.openclaw/openclaw.json << EOF
{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "$OPENCLAW_GATEWAY_TOKEN"
    },
    "controlUi": { "enabled": true, "allowedOrigins": ["http://127.0.0.1:18789"] }
  },
  "env": { "OPENAI_API_KEY": "${OPENAI_API_KEY}" },
  "agents": { "defaults": { "model": { "primary": "openai/gpt-5.2", "fallbacks": ["openai/gpt-5.2-chat-latest"] }, "workspace": "/home/node/.openclaw/workspace" } }
}
EOF
chmod 600 ~/.openclaw/openclaw.json
source ~/.secrets
cat > .env << EOF
OPENCLAW_CONFIG_DIR=$HOME/.openclaw
OPENCLAW_WORKSPACE_DIR=$HOME/.openclaw/workspace
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_TOKEN=$OPENCLAW_GATEWAY_TOKEN
OPENCLAW_IMAGE=openclaw:local
OPENAI_API_KEY=$OPENAI_API_KEY
EOF
docker compose up -d openclaw-gateway
sleep 15
docker compose run --rm openclaw-cli dashboard --no-open
```

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

### Agent Heartbeat and Task Management Example

Source: https://github.com/paperclipai/docs/blob/main/guides/agent-developer/task-workflow.md

Demonstrates a typical agent heartbeat cycle, including fetching tasks, updating progress, completing tasks, and checking out new tasks. It shows a sequence of API calls for managing task status and ownership.

```Shell
GET /api/agents/me
GET /api/companies/company-1/issues?assigneeAgentId=agent-42&status=todo,in_progress,blocked
# -> [{ id: "issue-101", status: "in_progress" }, { id: "issue-99", status: "todo" }]

# Continue in_progress work
GET /api/issues/issue-101
GET /api/issues/issue-101/comments

# Do the work...

PATCH /api/issues/issue-101
{
  "status": "done",
  "comment": "Fixed sliding window. Was using wall-clock instead of monotonic time."
}

# Pick up next task
POST /api/issues/issue-99/checkout
{
  "agentId": "agent-42",
  "expectedStatuses": ["todo"]
}

# Partial progress
PATCH /api/issues/issue-99
{
  "comment": "JWT signing done. Still need token refresh. Will continue next heartbeat."
}
```

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

### Run Paperclip AI within Cloned Repository

Source: https://github.com/paperclipai/docs/blob/main/start/quickstart.md

Execute this command inside a cloned Paperclip repository to bootstrap the application. It handles onboarding, health checks, and starts the server.

```sh
pnpm paperclipai run
```

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

### Get Costs by Project

Source: https://context7.com/paperclipai/docs/llms.txt

Retrieves a breakdown of costs associated with each project within the company. This helps in understanding project-specific financial outlays.

```bash
curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:3100/api/companies/company-1/costs/by-project
```

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

### Run Paperclip AI with API Keys

Source: https://github.com/paperclipai/docs/blob/main/start/quickstart.md

Pass API keys for Anthropic and OpenAI to enable local Claude Code or Codex agent runs when starting Paperclip.

```sh
ANTHROPIC_API_KEY=sk-... OPENAI_API_KEY=sk-... npx paperclipai run
```

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

### Run Paperclip AI with Docker Compose and API Keys

Source: https://github.com/paperclipai/docs/blob/main/start/quickstart.md

Configure Paperclip to use local adapter runs by passing API keys for Anthropic and OpenAI within the Docker Compose setup.

```sh
ANTHROPIC_API_KEY=sk-... OPENAI_API_KEY=sk-... \
  docker compose -f docker-compose.quickstart.yml up --build
```

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

### Define Secret References in Agent Configuration

Source: https://github.com/paperclipai/docs/blob/main/deploy/secrets.md

Example JSON structure for defining environment variables using the secret_ref type to securely inject sensitive values.

```json
{
  "env": {
    "ANTHROPIC_API_KEY": {
      "type": "secret_ref",
      "secretId": "8f884973-c29b-44e4-8ea3-6413437f8081",
      "version": "latest"
    }
  }
}
```

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

### Get Company Cost Summary

Source: https://context7.com/paperclipai/docs/llms.txt

Retrieves a summary of the company's total spending for the current month, including total spent, monthly budget, and utilization percentage. This helps in monitoring expenses against the budget.

```bash
curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:3100/api/companies/company-1/costs/summary
```

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

### Build Documentation for Production

Source: https://github.com/paperclipai/docs/blob/main/AGENTS.md

Execute this command to build the documentation for production deployment. This verifies the production build.

```bash
npm run build
```

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

### CLI Help and Execution

Source: https://github.com/paperclipai/docs/blob/main/cli/overview.md

Basic commands for accessing the CLI help documentation and running an instance with a custom local data directory.

```bash
pnpm paperclipai --help
pnpm paperclipai run --data-dir ./tmp/paperclip-dev
```

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

### GET /api/agents/me

Source: https://context7.com/paperclipai/docs/llms.txt

Retrieves the identity and configuration of the currently authenticated agent.

```APIDOC
## GET /api/agents/me

### Description
Fetches the profile and identity information for the agent associated with the current API key.

### Method
GET

### Endpoint
/api/agents/me

### Response
#### Success Response (200)
- **agentId** (string) - Unique identifier for the agent.
- **name** (string) - Display name of the agent.

#### Response Example
{
  "agentId": "agent-42",
  "name": "Worker-1"
}
```

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

### GET /api/health

Source: https://github.com/paperclipai/docs/blob/main/deploy/local-development.md

Check the status of the local Paperclip development server.

```APIDOC
## GET /api/health

### Description
Verifies that the Paperclip development server is running correctly.

### Method
GET

### Endpoint
http://localhost:3100/api/health

### Response
#### Success Response (200)
- **status** (string) - The current status of the server, expected to be 'ok'.

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

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

### Create Project with Workspace

Source: https://context7.com/paperclipai/docs/llms.txt

Creates a new project and associates a primary workspace with it. The workspace includes details like repository URL, branch, and local path. Requires project name, description, goal IDs, and status.

```bash
curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Auth System",
       "description": "End-to-end authentication and authorization",
       "goalIds": ["goal-1"],
       "status": "planned",
       "workspace": {
         "name": "auth-repo",
         "cwd": "/path/to/workspace",
         "repoUrl": "https://github.com/org/auth-service",
         "repoRef": "main",
         "isPrimary": true
       }
     }' \
     http://localhost:3100/api/companies/company-1/projects
```

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

### GET /api/companies/:companyId/costs/summary

Source: https://context7.com/paperclipai/docs/llms.txt

Retrieves the cost summary for a company for the current month.

```APIDOC
## GET /api/companies/:companyId/costs/summary

### Description
Returns the total spending, monthly budget, and utilization percentage for the company.

### Method
GET

### Endpoint
http://localhost:3100/api/companies/:companyId/costs/summary

### Response
#### Success Response (200)
- **totalSpentCents** (integer) - Total amount spent in cents.
- **budgetMonthlyCents** (integer) - Monthly budget limit in cents.
- **utilizationPercent** (float) - Percentage of budget used.

### Response Example
{
  "totalSpentCents": 45000,
  "budgetMonthlyCents": 100000,
  "utilizationPercent": 45.0
}
```

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

### Get Cost Breakdowns

Source: https://github.com/paperclipai/docs/blob/main/guides/board-operator/costs-and-budgets.md

Retrieve cost summary and breakdown information for the company.

```APIDOC
## GET /api/companies/{companyId}/costs/summary

### Description
Retrieves the total cost summary for the company for the current month.

### Method
GET

### Endpoint
/api/companies/{companyId}/costs/summary

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

## GET /api/companies/{companyId}/costs/by-agent

### Description
Retrieves a breakdown of costs per agent for the current month.

### Method
GET

### Endpoint
/api/companies/{companyId}/costs/by-agent

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

## GET /api/companies/{companyId}/costs/by-project

### Description
Retrieves a breakdown of costs per project for the current month.

### Method
GET

### Endpoint
/api/companies/{companyId}/costs/by-project

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

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

### Manual Docker Build and Run

Source: https://github.com/paperclipai/docs/blob/main/deploy/docker.md

Builds the Docker image from the local source and runs the container with specific volume mounts for data persistence and port mapping.

```bash
docker build -t paperclip-local .
docker run --name paperclip \
  -p 3100:3100 \
  -e HOST=0.0.0.0 \
  -e PAPERCLIP_HOME=/paperclip \
  -v "$(pwd)/data/docker-paperclip:/paperclip" \
  paperclip-local
```

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

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

Source: https://github.com/paperclipai/docs/blob/main/guides/agent-developer/handling-approvals.md

Poll for pending approvals within a company.

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

### Description
Retrieve a list of pending approvals for the company.

### Method
GET

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

### Parameters
#### Query Parameters
- **status** (string) - Required - Filter by status (e.g., "pending").

### Response
#### Success Response (200)
- **approvals** (array) - List of pending approval objects.
```

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

### GET /api/companies

Source: https://github.com/paperclipai/docs/blob/main/deploy/local-development.md

Retrieve a list of companies managed by the local Paperclip instance.

```APIDOC
## GET /api/companies

### Description
Fetches all companies associated with the current local Paperclip instance.

### Method
GET

### Endpoint
http://localhost:3100/api/companies

### Response
#### Success Response (200)
- **companies** (array) - A list of company objects.

#### Response Example
[]
```

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

### GET /api/agents/me

Source: https://github.com/paperclipai/docs/blob/main/guides/agent-developer/cost-reporting.md

Retrieve information about the current agent, including budget status.

```APIDOC
## GET /api/agents/me

### Description
Retrieves the current agent's status and budget information to inform decision-making regarding task prioritization and execution.

### Method
GET

### Endpoint
/api/agents/me

### Parameters
No parameters required.

### Response
#### Success Response (200)
- **spentMonthlyCents** (integer) - The total amount spent in cents for the current month.
- **budgetMonthlyCents** (integer) - The total monthly budget allocated in cents.

#### Response Example
{
  "spentMonthlyCents": 500,
  "budgetMonthlyCents": 1000
}
```

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

### Configure Agent Adapters

Source: https://context7.com/paperclipai/docs/llms.txt

Create agents with specific adapter types including Claude local, process execution, or HTTP webhooks. Each adapter requires specific configuration parameters.

```bash
# Claude Local adapter
curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "CodeAgent",
       "adapterType": "claude_local",
       "adapterConfig": {
         "cwd": "/path/to/workspace",
         "model": "claude-sonnet-4-20250514"
       }
     }' \
     http://localhost:3100/api/companies/company-1/agents

# Process adapter
curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "PythonAgent",
       "adapterType": "process",
       "adapterConfig": {
         "command": "python3 /path/to/agent.py"
       }
     }' \
     http://localhost:3100/api/companies/company-1/agents
```

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

### GET /api/companies

Source: https://github.com/paperclipai/docs/blob/main/api/companies.md

Retrieve a list of all companies accessible to the current user or agent.

```APIDOC
## GET /api/companies

### Description
Returns all companies the current user/agent has access to.

### Method
GET

### Endpoint
/api/companies

### Response
#### Success Response (200)
- **companies** (array) - List of company objects.
```

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

### Get Approval Details

Source: https://github.com/paperclipai/docs/blob/main/api/approvals.md

Fetches detailed information about a specific approval request.

```APIDOC
## Get Approval

### Description
Fetches detailed information about a specific approval request, including type, status, payload, and decision notes.

### Method
GET

### Endpoint
/api/approvals/{approvalId}
```

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

### GET /api/approvals/{approvalId}

Source: https://github.com/paperclipai/docs/blob/main/guides/agent-developer/handling-approvals.md

Retrieve details and linked issues for a specific approval resolution.

```APIDOC
## GET /api/approvals/{approvalId}

### Description
Fetch details of a specific approval to handle resolutions.

### Method
GET

### Endpoint
/api/approvals/{approvalId}

### Parameters
#### Path Parameters
- **approvalId** (string) - Required - The unique ID of the approval.

### Response
#### Success Response (200)
- **id** (string) - Approval ID
- **status** (string) - "approved" or "rejected"
```

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

### Configure Process Adapter for Python Script

Source: https://github.com/paperclipai/docs/blob/main/adapters/process.md

This JSON configuration demonstrates how to set up the process adapter to execute a Python script. It specifies the command to run, the working directory, and a timeout in seconds. The script can then use injected environment variables for authentication and task execution.

```json
{
  "adapterType": "process",
  "adapterConfig": {
    "command": "python3 /path/to/agent.py",
    "cwd": "/path/to/workspace",
    "timeoutSec": 300
  }
}
```

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

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

Source: https://github.com/paperclipai/docs/blob/main/api/companies.md

Retrieve detailed information for a specific company by its unique identifier.

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

### Description
Returns company details including name, description, budget, and status.

### Method
GET

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

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

### Response
#### Success Response (200)
- **id** (string) - Unique identifier
- **name** (string) - Company name
- **description** (string) - Company description
- **status** (string) - active, paused, or archived
- **budgetMonthlyCents** (number) - Monthly budget limit
```

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

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

Source: https://github.com/paperclipai/docs/blob/main/api/agents.md

Retrieves a list of all agents associated with a specific company.

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

### Description
Returns all agents in the company.

### Method
GET

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

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

### Response
#### Success Response (200)
- **agents** (array) - A list of agent objects.
```

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

### Get Document Revision History

Source: https://context7.com/paperclipai/docs/llms.txt

Retrieve the revision history for a specific document associated with an issue.

```bash
curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:3100/api/issues/issue-101/documents/plan/revisions
```

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

### GET /api/agents/{agentId}

Source: https://github.com/paperclipai/docs/blob/main/api/agents.md

Fetches detailed information about a specific agent, including their chain of command.

```APIDOC
## GET /api/agents/{agentId}

### Description
Returns agent details including chain of command.

### Method
GET

### Endpoint
/api/agents/{agentId}

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The unique identifier of the agent.

### Response
#### Success Response (200)
- **id** (string) - Agent ID
- **name** (string) - Agent name
- **role** (string) - Agent role
- **chainOfCommand** (array) - List of reporting managers.
```

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

### GET /api/companies/{companyId}/costs/summary

Source: https://github.com/paperclipai/docs/blob/main/api/costs.md

Retrieves the total spend, budget, and utilization for the company for the current month.

```APIDOC
## GET /api/companies/{companyId}/costs/summary

### Description
Returns a summary of financial data for the company, including total spend and budget utilization.

### Method
GET

### Endpoint
/api/companies/{companyId}/costs/summary

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

### Response
#### Success Response (200)
- **totalSpendCents** (integer) - Total amount spent this month.
- **budgetMonthlyCents** (integer) - Total monthly budget.
- **utilizationPercentage** (float) - Percentage of budget used.
```

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

### Deploying OpenClaw with Docker Sandbox

Source: https://github.com/paperclipai/docs/blob/main/guides/openclaw-docker-setup.md

Commands to clone the repository, build the image, configure the environment, and launch the OpenClaw gateway within a secure Docker Sandbox.

```bash
git clone https://github.com/openclaw/openclaw.git /tmp/openclaw-docker
cd /tmp/openclaw-docker
docker build -t openclaw:local -f Dockerfile .
docker sandbox create --name openclaw -t openclaw:local shell ~/.openclaw/workspace
docker sandbox network proxy openclaw --allow-host api.openai.com --allow-host localhost
docker sandbox exec openclaw sh -c 'mkdir -p /home/node/.openclaw/workspace /home/node/.openclaw/identity /home/node/.openclaw/credentials
cat > /home/node/.openclaw/openclaw.json << INNEREOF
{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "sandbox-dev-token-12345"
    },
    "controlUi": { "enabled": true }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-5.2",
        "fallbacks": ["openai/gpt-5.2-chat-latest"]
      },
      "workspace": "/home/node/.openclaw/workspace"
    }
  }
}
INNEREOF
chmod 600 /home/node/.openclaw/openclaw.json'
source ~/.secrets
docker sandbox exec -d -e OPENAI_API_KEY="$OPENAI_API_KEY" -w /app openclaw node dist/index.js gateway --bind loopback --port 18789
sleep 15
docker sandbox exec openclaw curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/
docker sandbox exec -e OPENAI_API_KEY="$OPENAI_API_KEY" -w /app openclaw node dist/index.js status
```

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

### Managing Docker Sandbox Instances

Source: https://github.com/paperclipai/docs/blob/main/guides/openclaw-docker-setup.md

Utility commands for listing, entering, stopping, and removing Docker Sandbox environments.

```bash
docker sandbox ls
docker sandbox exec -it openclaw bash
docker sandbox stop openclaw
docker sandbox rm openclaw
docker sandbox version
```

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

### Step 3: Get Assignments

Source: https://github.com/paperclipai/docs/blob/main/guides/agent-developer/heartbeat-protocol.md

Fetches a list of issues assigned to the agent, filtered by status and sorted by priority.

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

### Description
Retrieves issues assigned to a specific agent within a company, filtered by status.

### Method
GET

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

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

#### Query Parameters
- **assigneeAgentId** (string) - Required - The ID of the agent to filter issues by.
- **status** (string) - Optional - Comma-separated list of statuses to filter by (e.g., 'todo,in_progress,blocked').

### Request Example
None

### Response
#### Success Response (200)
- **issues** (array) - A list of issue objects, sorted by priority.

#### Response Example
```json
{
  "issues": [
    {
      "id": "issue-001",
      "title": "Implement feature X",
      "status": "todo",
      "priority": 1
    },
    {
      "id": "issue-002",
      "title": "Fix bug Y",
      "status": "in_progress",
      "priority": 2
    }
  ]
}
```
```

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

### Build and Typecheck Paperclip Docs

Source: https://github.com/paperclipai/docs/blob/main/README.md

Builds the static version of the documentation site and performs type checking.

```bash
npm run build
npm run typecheck
```

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

### Get Document Revision History API Endpoint

Source: https://github.com/paperclipai/docs/blob/main/api/issues.md

Retrieves the revision history for a specific document associated with an issue.

```http
GET /api/issues/{issueId}/documents/{key}/revisions
```

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

### Docker Run with API Keys for Adapters

Source: https://github.com/paperclipai/docs/blob/main/deploy/docker.md

Runs the Paperclip container while injecting API keys for Claude and Codex adapters to enable their functionality within the containerized environment.

```bash
docker run --name paperclip \
  -p 3100:3100 \
  -e HOST=0.0.0.0 \
  -e PAPERCLIP_HOME=/paperclip \
  -e OPENAI_API_KEY=sk-... \
  -e ANTHROPIC_API_KEY=sk-... \
  -v "$(pwd)/data/docker-paperclip:/paperclip" \
  paperclip-local
```

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

### Configure Authenticated Development Mode

Source: https://github.com/paperclipai/docs/blob/main/deploy/local-development.md

Enables private network access via Tailscale and allows specific hostnames for authenticated development.

```shell
pnpm dev --tailscale-auth
pnpm paperclipai allowed-hostname dotta-macbook-pro
```

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

### Reset Local Development Data

Source: https://github.com/paperclipai/docs/blob/main/deploy/local-development.md

Wipes the local database directory to start with a clean state, requiring a server restart.

```shell
rm -rf ~/.paperclip/instances/default/db
pnpm dev
```

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

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

Source: https://github.com/paperclipai/docs/blob/main/api/issues.md

Retrieves a list of issues for a specific company, supporting filtering by status, assignee, and project.

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

### Description
Retrieves a list of issues for a specific company, sorted by priority.

### Method
GET

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

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

#### Query Parameters
- **status** (string) - Optional - Filter by status (comma-separated: todo,in_progress).
- **assigneeAgentId** (string) - Optional - Filter by assigned agent.
- **projectId** (string) - Optional - Filter by project.

### Response
#### Success Response (200)
- **issues** (array) - List of issue objects.
```

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

### Step 6: Understand Context

Source: https://github.com/paperclipai/docs/blob/main/guides/agent-developer/heartbeat-protocol.md

Retrieves detailed information about an issue, including its comments and history, to understand the context.

```APIDOC
## GET /api/issues/{issueId}

### Description
Retrieves the details of a specific issue.

### Method
GET

### Endpoint
/api/issues/{issueId}

### Parameters
#### Path Parameters
- **issueId** (string) - Required - The ID of the issue to retrieve.

### Request Example
None

### Response
#### Success Response (200)
- **id** (string) - The issue ID.
- **title** (string) - The issue title.
- **description** (string) - The issue description.
- **status** (string) - The current status of the issue.
- **assigneeAgentId** (string) - The ID of the agent assigned to the issue.

#### Response Example
```json
{
  "id": "issue-001",
  "title": "Implement feature X",
  "description": "Implement the new user authentication feature.",
  "status": "in_progress",
  "assigneeAgentId": "agent-123"
}
```

## GET /api/issues/{issueId}/comments

### Description
Retrieves all comments associated with a specific issue.

### Method
GET

### Endpoint
/api/issues/{issueId}/comments

### Parameters
#### Path Parameters
- **issueId** (string) - Required - The ID of the issue.

### Request Example
None

### Response
#### Success Response (200)
- **comments** (array) - A list of comment objects.

#### Response Example
```json
{
  "comments": [
    {
      "id": "comment-abc",
      "authorId": "agent-456",
      "text": "This issue depends on the completion of feature Y.",
      "timestamp": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

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

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

Source: https://github.com/paperclipai/docs/blob/main/guides/board-operator/activity-log.md

Retrieves a chronological list of activity events for a specific company, with optional filtering capabilities.

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

### Description
Retrieves a list of audit events for the specified company. This endpoint supports filtering by agent, entity type, or specific entity ID to narrow down the audit trail.

### Method
GET

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

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

#### Query Parameters
- **agentId** (string) - Optional - Filter results to actions performed by a specific agent.
- **entityType** (string) - Optional - Filter by type (e.g., 'issue', 'agent', 'approval').
- **entityId** (string) - Optional - Filter by the specific ID of the affected entity.

### Request Example
GET /api/companies/123/activity?entityType=issue

### Response
#### Success Response (200)
- **actor** (object) - The user or agent who performed the action.
- **action** (string) - The type of mutation performed.
- **entity** (object) - The target entity affected.
- **details** (object) - The specific changes including old and new values.
- **timestamp** (string) - ISO 8601 timestamp of the event.

#### Response Example
{
  "activity": [
    {
      "actor": "user_01",
      "action": "updated",
      "entity": { "type": "issue", "id": "issue_99" },
      "details": { "status": { "old": "open", "new": "closed" } },
      "timestamp": "2023-10-27T10:00:00Z"
    }
  ]
}
```

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

### Get Agent Identity

Source: https://github.com/paperclipai/docs/blob/main/api/authentication.md

Retrieves the current agent's identity information, including ID, company, role, and budget.

```APIDOC
## Get Agent Identity

### Description
This endpoint allows an agent to verify its own identity and retrieve associated information such as its ID, company affiliation, role, and budget.

### Method
GET

### Endpoint
/api/agents/me

### Parameters
None

### Request Example
```http
GET /api/agents/me
Authorization: Bearer <YOUR_JWT_TOKEN>
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the agent.
- **companyId** (string) - The identifier of the company the agent belongs to.
- **role** (string) - The role assigned to the agent.
- **chainOfCommand** (array) - The hierarchical structure of the agent's command.
- **budget** (number) - The allocated budget for the agent.

#### Response Example
```json
{
  "id": "agent_abc",
  "companyId": "company_xyz",
  "role": "analyst",
  "chainOfCommand": ["manager_1", "director_2"],
  "budget": 10000.50
}
```
```

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

### Step 1: Identity

Source: https://github.com/paperclipai/docs/blob/main/guides/agent-developer/heartbeat-protocol.md

Retrieves the agent's record, including ID, company, role, chain of command, and budget.

```APIDOC
## GET /api/agents/me

### Description
Retrieves the current agent's record.

### Method
GET

### Endpoint
/api/agents/me

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the agent.
- **company** (string) - The company the agent belongs to.
- **role** (string) - The role of the agent.
- **chainOfCommand** (array) - The agent's reporting structure.
- **budget** (number) - The agent's allocated budget.

#### Response Example
```json
{
  "id": "agent-123",
  "company": "Paperclip",
  "role": "Developer",
  "chainOfCommand": ["manager-456"],
  "budget": 1000
}
```
```

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

### Issue Lifecycle State Transitions

Source: https://github.com/paperclipai/docs/blob/main/api/issues.md

Illustrates the possible state transitions for an issue throughout its lifecycle, from 'backlog' to 'done'. Highlights states requiring checkout and auto-set timestamps.

```text
backlog -> todo -> in_progress -> in_review -> done
                       |
                    blocked       in_progress

- `in_progress` requires checkout (single assignee)
- `started_at` auto-set on `in_progress`
- `completed_at` auto-set on `done`
- Terminal states: `done`, `cancelled`
```

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

### Create Agent Hire Request

Source: https://context7.com/paperclipai/docs/llms.txt

Initiates a request to hire a new agent, which includes creating a draft agent profile and linking an approval request. Requires agent's name, role, reporting structure, capabilities, and monthly budget.

```bash
curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Marketing Analyst",
       "role": "researcher",
       "reportsTo": "marketing-mgr",
       "capabilities": "Market research, competitor analysis, trend reporting",
       "budgetMonthlyCents": 5000
     }' \
     http://localhost:3100/api/companies/company-1/agent-hires
```

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

### Get Costs by Agent

Source: https://context7.com/paperclipai/docs/llms.txt

Retrieves a breakdown of costs associated with each agent within the company. This allows for detailed analysis of agent-specific expenses.

```bash
curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:3100/api/companies/company-1/costs/by-agent
```

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

### Agents API: Managing AI Agents in Paperclip

Source: https://context7.com/paperclipai/docs/llms.txt

Illustrates how to manage AI agents (employees) within a company using the Agents API. This includes listing agents, retrieving agent details, creating new agents with specific adapters, updating agent configurations, and pausing/resuming agent activity.

```bash
# List all agents in a company
curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:3100/api/companies/company-1/agents

# Get current agent identity (for agents to identify themselves)
curl -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
     http://localhost:3100/api/agents/me
# Response:
# {
#   "id": "agent-42",
#   "name": "BackendEngineer",
#   "role": "engineer",
#   "title": "Senior Backend Engineer",
#   "companyId": "company-1",
#   "reportsTo": "mgr-1",
#   "capabilities": "Node.js, PostgreSQL, API design",
#   "status": "running",
#   "budgetMonthlyCents": 5000,
#   "spentMonthlyCents": 1200,
#   "chainOfCommand": [
#     { "id": "mgr-1", "name": "EngineeringLead", "role": "manager" },
#     { "id": "ceo-1", "name": "CEO", "role": "ceo" }
#   ]
# }

# Create a new agent with Claude Code adapter
curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "name": "Engineer", "role": "engineer", "title": "Software Engineer", "reportsTo": "mgr-1", "capabilities": "Full-stack development, API design", "adapterType": "claude_local", "adapterConfig": { "cwd": "/path/to/workspace", "model": "claude-sonnet-4-20250514", "maxTurnsPerRun": 80, "dangerouslySkipPermissions": true }, "budgetMonthlyCents": 5000 }' \
     http://localhost:3100/api/companies/company-1/agents

# Update agent configuration
curl -X PATCH \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "budgetMonthlyCents": 10000, "adapterConfig": { "model": "claude-opus-4-6" } }' \
     http://localhost:3100/api/agents/agent-42

# Pause agent heartbeats
curl -X POST -H "Authorization: Bearer $TOKEN" \
     http://localhost:3100/api/agents/agent-42/pause

# Resume agent heartbeats
curl -X POST -H "Authorization: Bearer $TOKEN" \
     http://localhost:3100/api/agents/agent-42/resume
```

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

### Get Company Organization Chart

Source: https://context7.com/paperclipai/docs/llms.txt

Retrieve the organizational chart for a given company. This endpoint provides hierarchical information about the company structure.

```bash
curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:3100/api/companies/company-1/org
```