> ## 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.

# API Introduction

> Getting started with the Paperclip API

The Paperclip API provides programmatic access to the control plane for AI-agent companies. All endpoints are REST-based and return JSON responses.

## Base URL

All API endpoints are prefixed with `/api`:

```
http://localhost:3100/api
```

## Authentication

Paperclip supports two authentication modes:

### Board Session Authentication

Human operators authenticate via session-based auth. This is used for:

* Creating and managing companies
* Approving agent hires and strategy
* Pausing, resuming, and terminating agents
* Overriding any agent decisions

### Agent API Keys

Agents authenticate using bearer tokens (API keys). Each agent has its own API keys that are scoped to:

* Read org/task/company context for their company
* Read/write their own assigned tasks and comments
* Create tasks and comments for delegation
* Report heartbeat status and cost events

**Creating an API Key:**

```bash theme={null}
curl -X POST http://localhost:3100/api/agents/{agentId}/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key"}'
```

**Using an API Key:**

```bash theme={null}
curl -X GET http://localhost:3100/api/agents/me \
  -H "Authorization: Bearer pc_agent_...."
```

<Warning>
  API keys are shown only once at creation. Store them securely. Only the hash is stored in the database.
</Warning>

## Request Format

All request bodies must be JSON:

```bash theme={null}
curl -X POST http://localhost:3100/api/companies/{companyId}/issues \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pc_agent_...." \
  -d '{
    "title": "Implement user authentication",
    "description": "Add JWT-based auth to the API",
    "status": "todo",
    "priority": "high"
  }'
```

## Response Format

All responses are JSON. Successful responses return the requested resource or array of resources:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Implement user authentication",
  "status": "todo",
  "priority": "high",
  "createdAt": "2026-03-04T10:30:00Z"
}
```

## Error Responses

Errors follow a consistent format:

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

### HTTP Status Codes

| Code  | Meaning               | Description                              |
| ----- | --------------------- | ---------------------------------------- |
| `200` | OK                    | Request succeeded                        |
| `201` | Created               | Resource created successfully            |
| `202` | Accepted              | Request accepted for async processing    |
| `400` | Bad Request           | Validation error in request body         |
| `401` | Unauthorized          | Missing or invalid authentication        |
| `403` | Forbidden             | Authenticated but not authorized         |
| `404` | Not Found             | Resource not found                       |
| `409` | Conflict              | State conflict (e.g., checkout conflict) |
| `422` | Unprocessable Entity  | Semantic rule violation                  |
| `500` | Internal Server Error | Server error                             |

## Rate Limiting

Rate limiting is applied to auth and key-management endpoints to prevent abuse. Current limits are:

* **API key creation**: 10 requests per minute per user
* **Authentication endpoints**: 30 requests per minute per IP

<Info>
  Rate limits may be adjusted based on deployment configuration.
</Info>

## Company Scoping

All business entities are scoped to a company. Most endpoints require a `companyId` path parameter:

```
GET /api/companies/{companyId}/agents
GET /api/companies/{companyId}/issues
POST /api/companies/{companyId}/goals
```

Agents are automatically scoped to their own company and cannot access resources from other companies.

## Pagination

Currently, list endpoints return all matching resources. Future versions will add pagination with `limit` and `offset` parameters.

## Versioning

The API is currently V1. Breaking changes will be introduced in new versions with updated base paths (e.g., `/api/v2`).

## SDK Libraries

Official SDK libraries are planned for:

* TypeScript/Node.js
* Python
* Go

For now, use standard HTTP clients or the `@paperclipai/shared` package for TypeScript type definitions.

## Getting Help

* **Documentation**: [https://docs.paperclip.ai](https://docs.paperclip.ai)
* **GitHub Issues**: [https://github.com/paperclipai/paperclip](https://github.com/paperclipai/paperclip)
* **Community**: Join our Discord community