API Reference

The ProBeya API is built on tRPC and exposes type-safe procedures over HTTP. This page covers the conventions, request format, and error handling that apply across all endpoints.

Base URL

https://acme.probeya.com/api/trpc

Replace acme.probeya.com with the application hostname for your tenant. The API is served by the Next.js application; there is no separate API origin in the supported self-hosted stack.

Request Format

Queries (GET)

tRPC queries map to HTTP GET requests. The input is encoded in the URL:

GET /api/trpc/workspace.list
GET /api/trpc/item.byId?input={"id":"itm_abc123"}

Mutations (POST)

tRPC mutations map to HTTP POST requests. The input is sent as JSON in the request body:

POST /api/trpc/item.create
Content-Type: application/json

{
  "title": "New task",
  "boardId": "brd_xyz789",
  "groupId": "grp_abc123"
}

Batch Requests

You can batch multiple procedure calls in a single HTTP request:

GET /api/trpc/workspace.list,project.list?input={"1":{"workspaceId":"ws_abc123"}}

Response Format

All responses follow the tRPC envelope format:

Success

{
  "result": {
    "data": {
      "id": "itm_abc123",
      "title": "My task",
      "status": "todo"
    }
  }
}

Error

{
  "error": {
    "message": "Item not found",
    "code": "NOT_FOUND",
    "data": {
      "httpStatus": 404,
      "path": "item.byId"
    }
  }
}

Error Codes

Code	HTTP Status	Description
BAD_REQUEST	400	Invalid input or missing required fields
UNAUTHORIZED	401	Missing or invalid authentication
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
CONFLICT	409	Resource already exists or state conflict
TOO_MANY_REQUESTS	429	Rate limit exceeded
INTERNAL_SERVER_ERROR	500	Unexpected server error

Pagination

List endpoints support cursor-based pagination:

GET /api/trpc/item.list?input={"boardId":"brd_xyz789","cursor":"itm_abc123","limit":50}

Response includes a nextCursor field:

{
  "result": {
    "data": {
      "items": [...],
      "nextCursor": "itm_def456"
    }
  }
}

Pass nextCursor as the cursor parameter in the next request to fetch the next page. When nextCursor is null, there are no more results.

Filtering and Sorting

List endpoints accept optional filter and sort parameters:

{
  "boardId": "brd_xyz789",
  "filter": {
    "status": { "eq": "in_progress" },
    "priority": { "in": ["high", "critical"] }
  },
  "sort": [{ "field": "createdAt", "direction": "desc" }],
  "limit": 50
}

Available Routers

Router	Description
organization	Organization endpoints
workspace	Workspace endpoints
project	Project endpoints
board	Board endpoints
item	Item endpoints
form	Form endpoints
auth	Authentication endpoints

See the individual API pages for detailed procedure documentation.