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

# Companies

> Create and manage companies in Paperclip

Companies are the top-level organizational unit in Paperclip. All agents, tasks, goals, and projects belong to a company.

## The Company Object

<ParamField path="id" type="string" required>
  Unique identifier for the company
</ParamField>

<ParamField path="name" type="string" required>
  Company name
</ParamField>

<ParamField path="description" type="string">
  Optional company description
</ParamField>

<ParamField path="status" type="string" required>
  Company status: `active`, `paused`, or `archived`
</ParamField>

<ParamField path="issuePrefix" type="string" required>
  Prefix for issue identifiers (e.g., "PAP" for PAP-123)
</ParamField>

<ParamField path="issueCounter" type="number" required>
  Current issue counter for generating identifiers
</ParamField>

<ParamField path="budgetMonthlyCents" type="number" required>
  Monthly budget in cents
</ParamField>

<ParamField path="spentMonthlyCents" type="number" required>
  Amount spent this month in cents
</ParamField>

<ParamField path="requireBoardApprovalForNewAgents" type="boolean" required>
  Whether new agent hires require board approval
</ParamField>

<ParamField path="brandColor" type="string">
  Hex color code for company branding
</ParamField>

<ParamField path="createdAt" type="string" required>
  ISO 8601 timestamp of creation
</ParamField>

<ParamField path="updatedAt" type="string" required>
  ISO 8601 timestamp of last update
</ParamField>

***

## List Companies

<CodeGroup>
  ```bash cURL theme={null}
  curl http://localhost:3100/api/companies
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('/api/companies');
  const companies = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme AI Corp",
    "description": "Building the future of AI agents",
    "status": "active",
    "issuePrefix": "ACME",
    "issueCounter": 42,
    "budgetMonthlyCents": 100000,
    "spentMonthlyCents": 35000,
    "requireBoardApprovalForNewAgents": true,
    "brandColor": "#6366f1",
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-03-04T12:00:00Z"
  }
]
```

<ResponseField name="data" type="array">
  Array of company objects
</ResponseField>

***

## Get Company

<CodeGroup>
  ```bash cURL theme={null}
  curl http://localhost:3100/api/companies/{companyId}
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(`/api/companies/${companyId}`);
  const company = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme AI Corp",
  "description": "Building the future of AI agents",
  "status": "active",
  "issuePrefix": "ACME",
  "issueCounter": 42,
  "budgetMonthlyCents": 100000,
  "spentMonthlyCents": 35000,
  "requireBoardApprovalForNewAgents": true,
  "brandColor": "#6366f1",
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-03-04T12:00:00Z"
}
```

***

## Create Company

<Note>
  Only instance admins can create companies. In `local_trusted` mode, this is automatic.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:3100/api/companies \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Acme AI Corp",
      "description": "Building the future of AI agents",
      "issuePrefix": "ACME"
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('/api/companies', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Acme AI Corp',
      description: 'Building the future of AI agents',
      issuePrefix: 'ACME'
    })
  });
  const company = await response.json();
  ```
</CodeGroup>

**Request Body:**

<ParamField body="name" type="string" required>
  Company name (1-100 characters)
</ParamField>

<ParamField body="description" type="string">
  Company description
</ParamField>

<ParamField body="issuePrefix" type="string">
  Issue identifier prefix (2-10 uppercase letters, defaults to auto-generated)
</ParamField>

<ParamField body="budgetMonthlyCents" type="number">
  Monthly budget in cents (defaults to 0)
</ParamField>

<ParamField body="requireBoardApprovalForNewAgents" type="boolean">
  Whether to require approval for new agents (defaults to false)
</ParamField>

**Response:** `201 Created`

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme AI Corp",
  "description": "Building the future of AI agents",
  "status": "active",
  "issuePrefix": "ACME",
  "issueCounter": 0,
  "budgetMonthlyCents": 0,
  "spentMonthlyCents": 0,
  "requireBoardApprovalForNewAgents": false,
  "brandColor": null,
  "createdAt": "2026-03-04T12:00:00Z",
  "updatedAt": "2026-03-04T12:00:00Z"
}
```

***

## Update Company

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH http://localhost:3100/api/companies/{companyId} \
    -H "Content-Type: application/json" \
    -d '{
      "description": "Leading AI agent platform",
      "brandColor": "#8b5cf6"
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(`/api/companies/${companyId}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      description: 'Leading AI agent platform',
      brandColor: '#8b5cf6'
    })
  });
  const company = await response.json();
  ```
</CodeGroup>

**Request Body:**

<ParamField body="name" type="string">
  Company name
</ParamField>

<ParamField body="description" type="string">
  Company description
</ParamField>

<ParamField body="status" type="string">
  Status: `active`, `paused`, or `archived`
</ParamField>

<ParamField body="brandColor" type="string">
  Hex color code (e.g., "#6366f1")
</ParamField>

<ParamField body="requireBoardApprovalForNewAgents" type="boolean">
  Whether to require approval for new agents
</ParamField>

**Response:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme AI Corp",
  "description": "Leading AI agent platform",
  "status": "active",
  "brandColor": "#8b5cf6",
  "updatedAt": "2026-03-04T12:30:00Z"
}
```

***

## Archive Company

Archive a company to mark it as inactive without deleting it.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:3100/api/companies/{companyId}/archive
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(`/api/companies/${companyId}/archive`, {
    method: 'POST'
  });
  const company = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme AI Corp",
  "status": "archived",
  "updatedAt": "2026-03-04T12:30:00Z"
}
```

***

## Delete Company

<Warning>
  This permanently deletes the company and all associated data. This action cannot be undone.
</Warning>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE http://localhost:3100/api/companies/{companyId}
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(`/api/companies/${companyId}`, {
    method: 'DELETE'
  });
  const result = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "ok": true
}
```

***

## Get Company Stats

Get aggregate statistics for all companies.

<CodeGroup>
  ```bash cURL theme={null}
  curl http://localhost:3100/api/companies/stats
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('/api/companies/stats');
  const stats = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "550e8400-e29b-41d4-a716-446655440000": {
    "agentCount": 12,
    "activeAgentCount": 8,
    "taskCount": 156,
    "openTaskCount": 23,
    "projectCount": 5
  }
}
```

***

## Error Responses

### 404 Not Found

```json theme={null}
{
  "error": "Company not found"
}
```

### 403 Forbidden

```json theme={null}
{
  "error": "Instance admin required"
}
```