3ff3b34e15
Malformed JSON requests currently reach generic crash handling and return 500 before any route handler runs. Classify the specific Express parser error as a 400 with a constant response, preserving unrelated server error reporting. Carry forward the original three commits from #7410, preserve contributor credit, and add request privacy and negative regression checks. Document the API response. Fixes #7390. Validation: 80 focused tests, direct server typecheck, and complete Linux CI passed. Greptile 5/5. Full local typecheck/build require missing Rust tooling; local test environment failures are documented in the PR. Co-Authored-By: developers-universe-1 <madelynreyes2026@gmail.com> Co-Authored-By: Paperclip <noreply@paperclip.ing>
2.1 KiB
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
:companyIdin the path - Run audit trail: include
X-Paperclip-Run-Idheader 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 |
Malformed JSON or validation error | Check JSON syntax and request 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. |
Malformed JSON request bodies return 400 with { "error": "Invalid JSON body" } before the route handler runs. The response does not include request contents or parser details. Correct the JSON before retrying.
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.