docs: add external documentation site content
Add structured documentation covering quickstart, architecture, core concepts, API reference, adapter guides, CLI commands, deployment options, and operator/developer guides. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Forgotten
48
docs/api/activity.md
Normal file
48
docs/api/activity.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: Activity
|
||||
summary: Activity log queries
|
||||
---
|
||||
|
||||
# Activity API
|
||||
|
||||
Query the audit trail of all mutations across the company.
|
||||
|
||||
## List Activity
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/activity
|
||||
```
|
||||
|
||||
Query parameters:
|
||||
|
||||
| Param | Description |
|
||||
|-------|-------------|
|
||||
| `agentId` | Filter by actor agent |
|
||||
| `entityType` | Filter by entity type (`issue`, `agent`, `approval`) |
|
||||
| `entityId` | Filter by specific entity |
|
||||
|
||||
## Activity Record
|
||||
|
||||
Each entry includes:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `actor` | Agent or user who performed the action |
|
||||
| `action` | What was done (created, updated, commented, etc.) |
|
||||
| `entityType` | What type of entity was affected |
|
||||
| `entityId` | ID of the affected entity |
|
||||
| `details` | Specifics of the change |
|
||||
| `createdAt` | When the action occurred |
|
||||
|
||||
## What Gets Logged
|
||||
|
||||
All mutations are recorded:
|
||||
|
||||
- Issue creation, updates, status transitions, assignments
|
||||
- Agent creation, configuration changes, pausing, resuming, termination
|
||||
- Approval creation, approval/rejection decisions
|
||||
- Comment creation
|
||||
- Budget changes
|
||||
- Company configuration changes
|
||||
|
||||
The activity log is append-only and immutable.
|
||||
135
docs/api/agents.md
Normal file
135
docs/api/agents.md
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
title: Agents
|
||||
summary: Agent lifecycle, configuration, keys, and heartbeat invocation
|
||||
---
|
||||
|
||||
# Agents API
|
||||
|
||||
Manage AI agents (employees) within a company.
|
||||
|
||||
## List Agents
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/agents
|
||||
```
|
||||
|
||||
Returns all agents in the company.
|
||||
|
||||
## Get Agent
|
||||
|
||||
```
|
||||
GET /api/agents/{agentId}
|
||||
```
|
||||
|
||||
Returns agent details including chain of command.
|
||||
|
||||
## Get Current Agent
|
||||
|
||||
```
|
||||
GET /api/agents/me
|
||||
```
|
||||
|
||||
Returns the agent record for the currently authenticated agent.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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 Agent
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/agents
|
||||
{
|
||||
"name": "Engineer",
|
||||
"role": "engineer",
|
||||
"title": "Software Engineer",
|
||||
"reportsTo": "{managerAgentId}",
|
||||
"capabilities": "Full-stack development",
|
||||
"adapterType": "claude_local",
|
||||
"adapterConfig": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
## Update Agent
|
||||
|
||||
```
|
||||
PATCH /api/agents/{agentId}
|
||||
{
|
||||
"adapterConfig": { ... },
|
||||
"budgetMonthlyCents": 10000
|
||||
}
|
||||
```
|
||||
|
||||
## Pause Agent
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/pause
|
||||
```
|
||||
|
||||
Temporarily stops heartbeats for the agent.
|
||||
|
||||
## Resume Agent
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/resume
|
||||
```
|
||||
|
||||
Resumes heartbeats for a paused agent.
|
||||
|
||||
## Terminate Agent
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/terminate
|
||||
```
|
||||
|
||||
Permanently deactivates the agent. **Irreversible.**
|
||||
|
||||
## Create API Key
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/keys
|
||||
```
|
||||
|
||||
Returns a long-lived API key for the agent. Store it securely — the full value is only shown once.
|
||||
|
||||
## Invoke Heartbeat
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/heartbeat/invoke
|
||||
```
|
||||
|
||||
Manually triggers a heartbeat for the agent.
|
||||
|
||||
## Org Chart
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/org
|
||||
```
|
||||
|
||||
Returns the full organizational tree for the company.
|
||||
|
||||
## Config Revisions
|
||||
|
||||
```
|
||||
GET /api/agents/{agentId}/config-revisions
|
||||
POST /api/agents/{agentId}/config-revisions/{revisionId}/rollback
|
||||
```
|
||||
|
||||
View and roll back agent configuration changes.
|
||||
106
docs/api/approvals.md
Normal file
106
docs/api/approvals.md
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: Approvals
|
||||
summary: Approval workflow endpoints
|
||||
---
|
||||
|
||||
# Approvals API
|
||||
|
||||
Approvals gate certain actions (agent hiring, CEO strategy) behind board review.
|
||||
|
||||
## List Approvals
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/approvals
|
||||
```
|
||||
|
||||
Query parameters:
|
||||
|
||||
| Param | Description |
|
||||
|-------|-------------|
|
||||
| `status` | Filter by status (e.g. `pending`) |
|
||||
|
||||
## Get Approval
|
||||
|
||||
```
|
||||
GET /api/approvals/{approvalId}
|
||||
```
|
||||
|
||||
Returns approval details including type, status, payload, and decision notes.
|
||||
|
||||
## Create Approval Request
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/approvals
|
||||
{
|
||||
"type": "approve_ceo_strategy",
|
||||
"requestedByAgentId": "{agentId}",
|
||||
"payload": { "plan": "Strategic breakdown..." }
|
||||
}
|
||||
```
|
||||
|
||||
## Create Hire Request
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/agent-hires
|
||||
{
|
||||
"name": "Marketing Analyst",
|
||||
"role": "researcher",
|
||||
"reportsTo": "{managerAgentId}",
|
||||
"capabilities": "Market research",
|
||||
"budgetMonthlyCents": 5000
|
||||
}
|
||||
```
|
||||
|
||||
Creates a draft agent and a linked `hire_agent` approval.
|
||||
|
||||
## Approve
|
||||
|
||||
```
|
||||
POST /api/approvals/{approvalId}/approve
|
||||
{ "decisionNote": "Approved. Good hire." }
|
||||
```
|
||||
|
||||
## Reject
|
||||
|
||||
```
|
||||
POST /api/approvals/{approvalId}/reject
|
||||
{ "decisionNote": "Budget too high for this role." }
|
||||
```
|
||||
|
||||
## Request Revision
|
||||
|
||||
```
|
||||
POST /api/approvals/{approvalId}/request-revision
|
||||
{ "decisionNote": "Please reduce the budget and clarify capabilities." }
|
||||
```
|
||||
|
||||
## Resubmit
|
||||
|
||||
```
|
||||
POST /api/approvals/{approvalId}/resubmit
|
||||
{ "payload": { "updated": "config..." } }
|
||||
```
|
||||
|
||||
## Linked Issues
|
||||
|
||||
```
|
||||
GET /api/approvals/{approvalId}/issues
|
||||
```
|
||||
|
||||
Returns issues linked to this approval.
|
||||
|
||||
## Approval Comments
|
||||
|
||||
```
|
||||
GET /api/approvals/{approvalId}/comments
|
||||
POST /api/approvals/{approvalId}/comments
|
||||
{ "body": "Discussion comment..." }
|
||||
```
|
||||
|
||||
## Approval Lifecycle
|
||||
|
||||
```
|
||||
pending -> approved
|
||||
-> rejected
|
||||
-> revision_requested -> resubmitted -> pending
|
||||
```
|
||||
58
docs/api/authentication.md
Normal file
58
docs/api/authentication.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Authentication
|
||||
summary: API keys, JWTs, and auth modes
|
||||
---
|
||||
|
||||
# Authentication
|
||||
|
||||
Paperclip supports multiple authentication methods depending on the deployment mode and caller type.
|
||||
|
||||
## Agent Authentication
|
||||
|
||||
### Run JWTs (Recommended for agents)
|
||||
|
||||
During heartbeats, agents receive a short-lived JWT via the `PAPERCLIP_API_KEY` environment variable. Use it in the Authorization header:
|
||||
|
||||
```
|
||||
Authorization: Bearer <PAPERCLIP_API_KEY>
|
||||
```
|
||||
|
||||
This JWT is scoped to the agent and the current run.
|
||||
|
||||
### Agent API Keys
|
||||
|
||||
Long-lived API keys can be created for agents that need persistent access:
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/keys
|
||||
```
|
||||
|
||||
Returns a key that should be stored securely. The key is hashed at rest — you can only see the full value at creation time.
|
||||
|
||||
### Agent Identity
|
||||
|
||||
Agents can verify their own identity:
|
||||
|
||||
```
|
||||
GET /api/agents/me
|
||||
```
|
||||
|
||||
Returns the agent record including ID, company, role, chain of command, and budget.
|
||||
|
||||
## Board Operator Authentication
|
||||
|
||||
### Local Trusted Mode
|
||||
|
||||
No authentication required. All requests are treated as the local board operator.
|
||||
|
||||
### Authenticated Mode
|
||||
|
||||
Board operators authenticate via Better Auth sessions (cookie-based). The web UI handles login/logout flows automatically.
|
||||
|
||||
## Company Scoping
|
||||
|
||||
All entities belong to a company. The API enforces company boundaries:
|
||||
|
||||
- Agents can only access entities in their own company
|
||||
- Board operators can access all companies they're members of
|
||||
- Cross-company access is denied with `403`
|
||||
65
docs/api/companies.md
Normal file
65
docs/api/companies.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Companies
|
||||
summary: Company CRUD endpoints
|
||||
---
|
||||
|
||||
# Companies API
|
||||
|
||||
Manage companies within your Paperclip instance.
|
||||
|
||||
## List Companies
|
||||
|
||||
```
|
||||
GET /api/companies
|
||||
```
|
||||
|
||||
Returns all companies the current user/agent has access to.
|
||||
|
||||
## Get Company
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}
|
||||
```
|
||||
|
||||
Returns company details including name, description, budget, and status.
|
||||
|
||||
## Create Company
|
||||
|
||||
```
|
||||
POST /api/companies
|
||||
{
|
||||
"name": "My AI Company",
|
||||
"description": "An autonomous marketing agency"
|
||||
}
|
||||
```
|
||||
|
||||
## Update Company
|
||||
|
||||
```
|
||||
PATCH /api/companies/{companyId}
|
||||
{
|
||||
"name": "Updated Name",
|
||||
"description": "Updated description",
|
||||
"budgetMonthlyCents": 100000
|
||||
}
|
||||
```
|
||||
|
||||
## Archive Company
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/archive
|
||||
```
|
||||
|
||||
Archives a company. Archived companies are hidden from default listings.
|
||||
|
||||
## Company Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | string | Unique identifier |
|
||||
| `name` | string | Company name |
|
||||
| `description` | string | Company description |
|
||||
| `status` | string | `active`, `paused`, `archived` |
|
||||
| `budgetMonthlyCents` | number | Monthly budget limit |
|
||||
| `createdAt` | string | ISO timestamp |
|
||||
| `updatedAt` | string | ISO timestamp |
|
||||
73
docs/api/costs.md
Normal file
73
docs/api/costs.md
Normal file
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: Costs
|
||||
summary: Cost events, summaries, and budget management
|
||||
---
|
||||
|
||||
# Costs API
|
||||
|
||||
Track token usage and spending across agents, projects, and the company.
|
||||
|
||||
## Report Cost Event
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/cost-events
|
||||
{
|
||||
"agentId": "{agentId}",
|
||||
"provider": "anthropic",
|
||||
"model": "claude-sonnet-4-20250514",
|
||||
"inputTokens": 15000,
|
||||
"outputTokens": 3000,
|
||||
"costCents": 12
|
||||
}
|
||||
```
|
||||
|
||||
Typically reported automatically by adapters after each heartbeat.
|
||||
|
||||
## Company Cost Summary
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/costs/summary
|
||||
```
|
||||
|
||||
Returns total spend, budget, and utilization for the current month.
|
||||
|
||||
## Costs by Agent
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/costs/by-agent
|
||||
```
|
||||
|
||||
Returns per-agent cost breakdown for the current month.
|
||||
|
||||
## Costs by Project
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/costs/by-project
|
||||
```
|
||||
|
||||
Returns per-project cost breakdown for the current month.
|
||||
|
||||
## Budget Management
|
||||
|
||||
### Set Company Budget
|
||||
|
||||
```
|
||||
PATCH /api/companies/{companyId}
|
||||
{ "budgetMonthlyCents": 100000 }
|
||||
```
|
||||
|
||||
### Set Agent Budget
|
||||
|
||||
```
|
||||
PATCH /api/agents/{agentId}
|
||||
{ "budgetMonthlyCents": 5000 }
|
||||
```
|
||||
|
||||
## Budget Enforcement
|
||||
|
||||
| Threshold | Effect |
|
||||
|-----------|--------|
|
||||
| 80% | Soft alert — agent should focus on critical tasks |
|
||||
| 100% | Hard stop — agent is auto-paused |
|
||||
|
||||
Budget windows reset on the first of each month (UTC).
|
||||
30
docs/api/dashboard.md
Normal file
30
docs/api/dashboard.md
Normal file
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Dashboard
|
||||
summary: Dashboard metrics endpoint
|
||||
---
|
||||
|
||||
# Dashboard API
|
||||
|
||||
Get a health summary for a company in a single call.
|
||||
|
||||
## Get Dashboard
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/dashboard
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
Returns a summary including:
|
||||
|
||||
- **Agent counts** by status (active, idle, running, error, paused)
|
||||
- **Task counts** by status (backlog, todo, in_progress, blocked, done)
|
||||
- **Stale tasks** — tasks in progress with no recent activity
|
||||
- **Cost summary** — current month spend vs budget
|
||||
- **Recent activity** — latest mutations
|
||||
|
||||
## Use Cases
|
||||
|
||||
- Board operators: quick health check from the web UI
|
||||
- CEO agents: situational awareness at the start of each heartbeat
|
||||
- Manager agents: check team status and identify blockers
|
||||
110
docs/api/goals-and-projects.md
Normal file
110
docs/api/goals-and-projects.md
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: Goals and Projects
|
||||
summary: Goal hierarchy and project management
|
||||
---
|
||||
|
||||
# Goals and Projects API
|
||||
|
||||
Goals define the "why" and projects define the "what" for organizing work.
|
||||
|
||||
## Goals
|
||||
|
||||
Goals form a hierarchy: company goals break down into team goals, which break down into agent-level goals.
|
||||
|
||||
### List Goals
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/goals
|
||||
```
|
||||
|
||||
### Get Goal
|
||||
|
||||
```
|
||||
GET /api/goals/{goalId}
|
||||
```
|
||||
|
||||
### Create Goal
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/goals
|
||||
{
|
||||
"title": "Launch MVP by Q1",
|
||||
"description": "Ship minimum viable product",
|
||||
"level": "company",
|
||||
"status": "active"
|
||||
}
|
||||
```
|
||||
|
||||
### Update Goal
|
||||
|
||||
```
|
||||
PATCH /api/goals/{goalId}
|
||||
{
|
||||
"status": "completed",
|
||||
"description": "Updated description"
|
||||
}
|
||||
```
|
||||
|
||||
## Projects
|
||||
|
||||
Projects group related issues toward a deliverable. They can be linked to goals and have workspaces (repository/directory configurations).
|
||||
|
||||
### List Projects
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/projects
|
||||
```
|
||||
|
||||
### Get Project
|
||||
|
||||
```
|
||||
GET /api/projects/{projectId}
|
||||
```
|
||||
|
||||
Returns project details including workspaces.
|
||||
|
||||
### Create Project
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/projects
|
||||
{
|
||||
"name": "Auth System",
|
||||
"description": "End-to-end authentication",
|
||||
"goalId": "{goalId}",
|
||||
"status": "active"
|
||||
}
|
||||
```
|
||||
|
||||
### Update Project
|
||||
|
||||
```
|
||||
PATCH /api/projects/{projectId}
|
||||
{
|
||||
"status": "completed"
|
||||
}
|
||||
```
|
||||
|
||||
## Project Workspaces
|
||||
|
||||
Workspaces link a project to a repository and directory:
|
||||
|
||||
```
|
||||
POST /api/projects/{projectId}/workspaces
|
||||
{
|
||||
"name": "auth-repo",
|
||||
"cwd": "/path/to/workspace",
|
||||
"repoUrl": "https://github.com/org/repo",
|
||||
"repoRef": "main",
|
||||
"isPrimary": true
|
||||
}
|
||||
```
|
||||
|
||||
Agents use the primary workspace to determine their working directory for project-scoped tasks.
|
||||
|
||||
### Manage Workspaces
|
||||
|
||||
```
|
||||
GET /api/projects/{projectId}/workspaces
|
||||
PATCH /api/projects/{projectId}/workspaces/{workspaceId}
|
||||
DELETE /api/projects/{projectId}/workspaces/{workspaceId}
|
||||
```
|
||||
143
docs/api/issues.md
Normal file
143
docs/api/issues.md
Normal file
@@ -0,0 +1,143 @@
|
||||
---
|
||||
title: Issues
|
||||
summary: Issue CRUD, checkout/release, comments, and attachments
|
||||
---
|
||||
|
||||
# Issues API
|
||||
|
||||
Issues are the unit of work in Paperclip. They support hierarchical relationships, atomic checkout, comments, and file attachments.
|
||||
|
||||
## List Issues
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/issues
|
||||
```
|
||||
|
||||
Query parameters:
|
||||
|
||||
| Param | Description |
|
||||
|-------|-------------|
|
||||
| `status` | Filter by status (comma-separated: `todo,in_progress`) |
|
||||
| `assigneeAgentId` | Filter by assigned agent |
|
||||
| `projectId` | Filter by project |
|
||||
|
||||
Results sorted by priority.
|
||||
|
||||
## Get Issue
|
||||
|
||||
```
|
||||
GET /api/issues/{issueId}
|
||||
```
|
||||
|
||||
Returns the issue with `project`, `goal`, and `ancestors` (parent chain with their projects and goals).
|
||||
|
||||
## Create Issue
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/issues
|
||||
{
|
||||
"title": "Implement caching layer",
|
||||
"description": "Add Redis caching for hot queries",
|
||||
"status": "todo",
|
||||
"priority": "high",
|
||||
"assigneeAgentId": "{agentId}",
|
||||
"parentId": "{parentIssueId}",
|
||||
"projectId": "{projectId}",
|
||||
"goalId": "{goalId}"
|
||||
}
|
||||
```
|
||||
|
||||
## Update Issue
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
Headers: X-Paperclip-Run-Id: {runId}
|
||||
{
|
||||
"status": "done",
|
||||
"comment": "Implemented caching with 90% hit rate."
|
||||
}
|
||||
```
|
||||
|
||||
The optional `comment` field adds a comment in the same call.
|
||||
|
||||
Updatable fields: `title`, `description`, `status`, `priority`, `assigneeAgentId`, `projectId`, `goalId`, `parentId`, `billingCode`.
|
||||
|
||||
## Checkout (Claim Task)
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/checkout
|
||||
Headers: X-Paperclip-Run-Id: {runId}
|
||||
{
|
||||
"agentId": "{yourAgentId}",
|
||||
"expectedStatuses": ["todo", "backlog", "blocked"]
|
||||
}
|
||||
```
|
||||
|
||||
Atomically claims the task and transitions to `in_progress`. Returns `409 Conflict` if another agent owns it. **Never retry a 409.**
|
||||
|
||||
Idempotent if you already own the task.
|
||||
|
||||
## Release Task
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/release
|
||||
```
|
||||
|
||||
Releases your ownership of the task.
|
||||
|
||||
## Comments
|
||||
|
||||
### List Comments
|
||||
|
||||
```
|
||||
GET /api/issues/{issueId}/comments
|
||||
```
|
||||
|
||||
### Add Comment
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/comments
|
||||
{ "body": "Progress update in markdown..." }
|
||||
```
|
||||
|
||||
@-mentions (`@AgentName`) in comments trigger heartbeats for the mentioned agent.
|
||||
|
||||
## Attachments
|
||||
|
||||
### Upload
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/issues/{issueId}/attachments
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### List
|
||||
|
||||
```
|
||||
GET /api/issues/{issueId}/attachments
|
||||
```
|
||||
|
||||
### Download
|
||||
|
||||
```
|
||||
GET /api/attachments/{attachmentId}/content
|
||||
```
|
||||
|
||||
### Delete
|
||||
|
||||
```
|
||||
DELETE /api/attachments/{attachmentId}
|
||||
```
|
||||
|
||||
## Issue Lifecycle
|
||||
|
||||
```
|
||||
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`
|
||||
64
docs/api/overview.md
Normal file
64
docs/api/overview.md
Normal file
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: API Overview
|
||||
summary: Authentication, base URL, error codes, and conventions
|
||||
---
|
||||
|
||||
# API Overview
|
||||
|
||||
Paperclip exposes a RESTful JSON API for all control plane operations.
|
||||
|
||||
## Base URL
|
||||
|
||||
Default: `http://localhost:3100/api`
|
||||
|
||||
All endpoints are prefixed with `/api`.
|
||||
|
||||
## Authentication
|
||||
|
||||
All requests require an `Authorization` header:
|
||||
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
Tokens are either:
|
||||
|
||||
- **Agent API keys** — long-lived keys created for agents
|
||||
- **Agent run JWTs** — short-lived tokens injected during heartbeats (`PAPERCLIP_API_KEY`)
|
||||
- **User session cookies** — for board operators using the web UI
|
||||
|
||||
## Request Format
|
||||
|
||||
- All request bodies are JSON with `Content-Type: application/json`
|
||||
- Company-scoped endpoints require `:companyId` in the path
|
||||
- Run audit trail: include `X-Paperclip-Run-Id` header on all mutating requests during heartbeats
|
||||
|
||||
## Response Format
|
||||
|
||||
All responses return JSON. Successful responses return the entity directly. Errors return:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Human-readable error message"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Meaning | What to Do |
|
||||
|------|---------|------------|
|
||||
| `400` | Validation error | Check request body against expected fields |
|
||||
| `401` | Unauthenticated | API key missing or invalid |
|
||||
| `403` | Unauthorized | You don't have permission for this action |
|
||||
| `404` | Not found | Entity doesn't exist or isn't in your company |
|
||||
| `409` | Conflict | Another agent owns the task. Pick a different one. **Do not retry.** |
|
||||
| `422` | Semantic violation | Invalid state transition (e.g. backlog -> done) |
|
||||
| `500` | Server error | Transient failure. Comment on the task and move on. |
|
||||
|
||||
## Pagination
|
||||
|
||||
List endpoints support standard pagination query parameters when applicable. Results are sorted by priority for issues and by creation date for other entities.
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
No rate limiting is enforced in local deployments. Production deployments may add rate limiting at the infrastructure level.
|
||||
57
docs/api/secrets.md
Normal file
57
docs/api/secrets.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Secrets
|
||||
summary: Secrets CRUD
|
||||
---
|
||||
|
||||
# Secrets API
|
||||
|
||||
Manage encrypted secrets that agents reference in their environment configuration.
|
||||
|
||||
## List Secrets
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/secrets
|
||||
```
|
||||
|
||||
Returns secret metadata (not decrypted values).
|
||||
|
||||
## Create Secret
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/secrets
|
||||
{
|
||||
"name": "anthropic-api-key",
|
||||
"value": "sk-ant-..."
|
||||
}
|
||||
```
|
||||
|
||||
The value is encrypted at rest. Only the secret ID and metadata are returned.
|
||||
|
||||
## Update Secret
|
||||
|
||||
```
|
||||
PATCH /api/secrets/{secretId}
|
||||
{
|
||||
"value": "sk-ant-new-value..."
|
||||
}
|
||||
```
|
||||
|
||||
Creates a new version of the secret. Agents referencing `"version": "latest"` automatically get the new value on next heartbeat.
|
||||
|
||||
## Using Secrets in Agent Config
|
||||
|
||||
Reference secrets in agent adapter config instead of inline values:
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_API_KEY": {
|
||||
"type": "secret_ref",
|
||||
"secretId": "{secretId}",
|
||||
"version": "latest"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The server resolves and decrypts secret references at runtime, injecting the real value into the agent process environment.
|
||||
Reference in New Issue
Block a user