Skip to content

API

Overview

Authentication, resource model, errors, and versioning for the ComeBk HTTP API.

  • API
  • 1 min read

Base URL and versioning

{COMEBK_API_BASE_URL}/v1

The path segment v1 is the public API major. Breaking changes ship under a new major; additive fields may appear within a major. Check Release notes before upgrading clients.

Authentication

Send a bearer token on every request:

Authorization: Bearer <token>
X-ComeBk-Tenant-Id: <tenant-id>

Tokens are scoped (opportunities:read, opportunities:write, admin:cycles, …). Missing scopes return 403 with the required scope name in the error body.

Core resources

| Resource | Path | Notes | | ------------- | ----------------- | ----------------------------------- | | Opportunities | /opportunities | Create, get, list, advance, archive | | Cycles | /admin/cycles | Admin configuration | | Channels | /admin/channels | Admin configuration | | Auth | /auth/whoami | Token and tenant verification |

List endpoints are cursor-paginated. Include query include=explanations (or include[]=explanations) when decision context is required.

Errors

Responses use a common envelope:

{
  "error": {
    "code": "invalid_transition",
    "message": "Stage 'book' is not allowed from 'qualify'",
    "details": { "allowed": ["structure"] }
  }
}

| HTTP | Typical meaning | | ----- | ------------------------------------------------ | | 400 | Validation failure | | 401 | Missing or invalid token | | 403 | Insufficient scope | | 404 | Unknown resource | | 409 | Conflict (invalid transition, concurrent update) | | 429 | Rate limited |

SDKs

The TypeScript SDK wraps these resources. See Installation and Quick start. For integration patterns: Integration guide.

Related