paperclip/docs/api/overview.md at f0b5130b807f4daeb984205a932a793eb9be91cb

Files

Dotta 09d2ef1a37 fix: restore docs deleted in v0.2.3 release, add Paperclip branding

- Restored docs/ directory that was accidentally deleted by `git add -A`
  in the v0.2.3 release script
- Replaced generic "P" favicon with actual paperclip icon using brand
  primary color (#2563EB)
- Added light/dark logo SVGs for Mintlify navbar (paperclip icon + wordmark)
- Updated docs.json with logo configuration for dark/light mode
- Fixed release.sh to stage only release-related files instead of `git add -A`
  to prevent sweeping unrelated changes into release commits

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-03 15:49:43 -06:00

1.9 KiB

Raw Blame History

title, summary

title	summary
API Overview	Authentication, base URL, error codes, and conventions

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:

{
  "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.

1.9 KiB Raw Blame History