Application API

TopoloCRM

Clear API and contract surface for TopoloCRM, grouped under the application instead of split across generic reference sections.

OpenAPI-backed srv_iCwM4jGXcwlj

Documentation Map

Authority

Service IDs:

srv_iCwM4jGXcwlj

Repos: PlatformApplications/TopoloCRM

Hosts:

https://crm.topolo.app

Dependencies: topolo-auth, topolo-one, applications-packages

Depends on Topolo Auth: yes

Contract Source

Type: generated OpenAPI

Source: PlatformApplications/TopoloCRM/packages/backend/openapi.yaml

Source exists: yes

CRM owns its worker API contract and delegates browser login, cookie refresh, logout propagation, one-time `sso_code` callback exchange, and shared-launcher Auth data reads to the shared Auth client plus same-origin `/api/auth/*` Pages gateway. The explicit `/login` route renders the branded shared LoginPage without an initial refresh probe, embedded password-login success returns to the CRM route tree after shared Auth token persistence, shared Auth token update events are treated as already-persisted state, and the browser app does not expose a legacy `/sso?token=` token handoff route or app-local `/sso/exchange` parser. CRM keeps same-tab sessionStorage access-token restore enabled by default after login and refresh so normal reloads do not appear logged out before cookie refresh completes. The callback route guards one-time code exchange with a fixed `/dashboard` completion target so Auth home-path re-resolution cannot retry an already consumed `sso_code`. CRM exposes `GET /api/widget` with the shared `@topolo/sdk` widget response contract for TopoloOne live workspace.

API key scopes in Auth catalog: 44

Auth Requirements

No global OpenAPI security scheme is declared.

  • activities.read
  • activities.write
  • api_keys.write
  • attachments.read
  • attachments.write
  • commissions.read
  • commissions.write
  • companies.read
  • companies.write
  • contacts.read
  • contacts.write
  • deals.read
  • deals.write
  • documents.read
  • documents.write
  • listings.read
  • listings.write
  • notes.read
  • notes.write
  • offers.read

Runtime and Deployment

Wrangler surfaces: PlatformApplications/TopoloCRM/app/wrangler.toml, PlatformApplications/TopoloCRM/packages/backend/wrangler.toml

Environment variables: API_KEY_HASH_ITERATIONS, API_KEY_PREFIX, AUTH_API_URL, ENVIRONMENT, NEXUS_GATEWAY_URL, NODE_ENV, SALT_ROUNDS, account_id

Routes: workers.dev or Pages-only delivery

Observability enabled: yes

Servers

  • http://localhost:8787 Local development server
  • https://your-worker.your-subdomain.workers.dev Production Cloudflare Worker

Operations

system
  • GET /health Health check Responses: 200
  • GET /api API information Responses: 200
contacts
  • GET /api/contacts List contacts Responses: 200, 500
  • POST /api/contacts Create contact Responses: 201, 400, 500
  • GET /api/contacts/{id} Get contact Responses: 200, 404, 500
  • PUT /api/contacts/{id} Update contact Responses: 200, 400, 404, 500
  • DELETE /api/contacts/{id} Delete contact Responses: 200, 404, 500
notes
  • GET /api/contacts/{id}/notes List contact notes Responses: 200, 404, 500
  • POST /api/contacts/{id}/notes Create note Responses: 201, 400, 404, 500
  • GET /api/contacts/{contactId}/notes/{noteId} Get specific note Responses: 200, 404, 500
  • PUT /api/contacts/{contactId}/notes/{noteId} Update note Responses: 200, 400, 404, 500
  • DELETE /api/contacts/{contactId}/notes/{noteId} Delete note Responses: 200, 404, 500
attachments
  • GET /api/contacts/{id}/attachments List contact attachments Responses: 200, 404, 500
  • POST /api/contacts/{id}/attachments Upload attachment Responses: 201, 400, 404, 413, 500
  • GET /api/attachments/{id} Download attachment Responses: 200, 404, 500
  • DELETE /api/attachments/{id} Delete attachment Responses: 200, 404, 500
pipeline
  • GET /api/pipeline List pipelines Responses: 200, 500
  • GET /api/pipeline/{pipelineId} Get pipeline details Responses: 200, 404, 500
  • GET /api/pipeline/{pipelineId}/board Get pipeline board Responses: 200, 404, 500
  • PUT /api/pipeline/{contactId}/move Move contact to stage Responses: 200, 400, 404, 500
  • GET /api/pipeline/{contactId}/history Get contact pipeline history Responses: 200, 404, 500
import-export
  • POST /api/contacts/import Import contacts Responses: 200, 400, 500
  • GET /api/contacts/export Export contacts Responses: 200, 500

Copyable cURL

GET /health

Health check

curl -X GET 'http://localhost:8787/health' \
  -H 'Accept: application/json'
GET /api

API information

curl -X GET 'http://localhost:8787/api' \
  -H 'Accept: application/json'
GET /api/contacts

List contacts

curl -X GET 'http://localhost:8787/api/contacts' \
  -H 'Accept: application/json'
POST /api/contacts

Create contact

curl -X POST 'http://localhost:8787/api/contacts' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
GET /api/contacts/{id}

Get contact

curl -X GET 'http://localhost:8787/api/contacts/{id}' \
  -H 'Accept: application/json'
PUT /api/contacts/{id}

Update contact

curl -X PUT 'http://localhost:8787/api/contacts/{id}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
DELETE /api/contacts/{id}

Delete contact

curl -X DELETE 'http://localhost:8787/api/contacts/{id}' \
  -H 'Accept: application/json'
GET /api/contacts/{id}/notes

List contact notes

curl -X GET 'http://localhost:8787/api/contacts/{id}/notes' \
  -H 'Accept: application/json'
POST /api/contacts/{id}/notes

Create note

curl -X POST 'http://localhost:8787/api/contacts/{id}/notes' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
GET /api/contacts/{contactId}/notes/{noteId}

Get specific note

curl -X GET 'http://localhost:8787/api/contacts/{contactId}/notes/{noteId}' \
  -H 'Accept: application/json'
PUT /api/contacts/{contactId}/notes/{noteId}

Update note

curl -X PUT 'http://localhost:8787/api/contacts/{contactId}/notes/{noteId}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
DELETE /api/contacts/{contactId}/notes/{noteId}

Delete note

curl -X DELETE 'http://localhost:8787/api/contacts/{contactId}/notes/{noteId}' \
  -H 'Accept: application/json'