​
Welcome to the ProBeya API

The ProBeya REST API gives you programmatic access to every resource in the platform — organizations, workspaces, projects, boards, items, KPIs, actions, and more. The API follows RESTful conventions and returns JSON for all responses.

Use the API to build integrations, automate workflows, ingest data from external systems (SAP, MES, QMS), or power custom dashboards.

​
Base URL

Every organization in ProBeya gets a dedicated subdomain. All REST API requests target that subdomain with a /api/v1 prefix:

https://{org}.probeya.com/api/v1

For example, if your organization slug is acme:

https://acme.probeya.com/api/v1/items
https://acme.probeya.com/api/v1/kpis
https://acme.probeya.com/api/v1/actions

The {org} placeholder is the slug you chose when creating your organization (visible in Settings > Organization > General). It is case-insensitive.

​
Authentication

Authenticate every request by including a Bearer token in the Authorization header. Tokens are created in Settings > API Tokens in the ProBeya dashboard.

curl https://acme.probeya.com/api/v1/items \
  -H "Authorization: Bearer probeya_sk_live_abc123..."

ProBeya supports two token types:

Token TypePrefixUse Case
Personal Access Tokenprobeya_sk_live_Server-to-server, scripts, CI/CD
OAuth Access Tokenprobeya_oat_Apps acting on behalf of a user

See Authentication for token creation, scopes, and OAuth 2.0 flows.

Never expose API keys in client-side code, public repositories, or browser-visible source. Rotate compromised keys immediately from the dashboard.

​
Response Format

All successful responses are wrapped in a standard JSON envelope containing a data field and an optional meta field for pagination metadata:

​
Single Resource

{
  "data": {
    "id": "itm_clx9abc123",
    "name": "Improve OEE on Line 3",
    "boardId": "brd_clx9xyz789",
    "status": "in_progress",
    "priority": "high",
    "createdAt": "2026-03-19T14:30:00.000Z",
    "updatedAt": "2026-03-25T09:15:00.000Z"
  }
}

​
Collection (List)

{
  "data": [
    {
      "id": "itm_clx9abc123",
      "name": "Improve OEE on Line 3",
      "status": "in_progress"
    },
    {
      "id": "itm_clx9def456",
      "name": "Root cause analysis — batch deviation",
      "status": "open"
    }
  ],
  "meta": {
    "cursor": "itm_clx9def456",
    "has_more": true,
    "limit": 50
  }
}

​
Error Response

Error responses use the same envelope with an error field instead of data:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "Validation failed",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      },
      {
        "field": "boardId",
        "message": "Invalid board ID format"
      }
    ]
  }
}

See Errors for the full error code reference.

​
Content Type

All request bodies must be sent as JSON with the Content-Type: application/json header:

curl -X POST https://acme.probeya.com/api/v1/items \
  -H "Authorization: Bearer probeya_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "boardId": "brd_clx9xyz789",
    "groupId": "grp_clx9abc123",
    "name": "New corrective action",
    "priority": "high"
  }'

​
Versioning

The API is versioned via the URL path (/api/v1). When breaking changes are introduced, a new version will be released (e.g., /api/v2). The previous version remains available for a minimum of 12 months after deprecation notice.

Non-breaking changes — such as new optional fields, new endpoints, or new enum values — are added to the current version without a version bump.

​
What’s Next

Pagination

Learn how cursor-based pagination works across list endpoints.

Rate Limiting

Understand request limits per plan and how to handle throttling.

Error Codes

Full reference for every error code the API can return.

Webhooks

Set up real-time event notifications for your integrations.

Was this page helpful?

Overview