Skip to main content

Getting started with API

Overview​

The Comindwork REST API lets you read and write data in your workspaces programmatically. Use it to build integrations, automate workflows, import/export data, and connect external services.

Base URL​

All API requests are sent to your Comindwork instance:

https://<your-company>.comind.work/api

For self-hosted installations, use your locally defined domain followed by /api.

HTTPS is required for all requests.

Endpoints overview​

EndpointMethodPurpose
/commonGETCurrent user context (ID, name, timezone, admin status)
/w/{WS}/a/{APP}/tickets/listPOSTList and filter records in a specific app
/tickets/listPOSTList records across all workspaces
/tickets/searchPOSTFull-text keyword search
/tickets/historyPOSTRecord change history with field diffs
/tickets/multiPOSTCreate, update, or delete records (batch)
/schema/{WS}!{APP}GETApp schema (fields, lookups, actions, layouts)
/projects/{WS}!WORKSPACEGETWorkspace info (apps, members, tabs)
/download/{uuid}GETDownload a file or image attachment

Authentication​

Requests use the Authorization header. Two token formats are supported:

Auth code (opaque token)​

Authorization: CMW_AUTH_CODE <your-token>

Auth codes are issued when you create an integration user. They are simple opaque tokens passed through to the backend.

Bearer token (JWT)​

Authorization: Bearer <jwt-token>

Bearer tokens are standard JWTs, validated via JWKS when an OIDC issuer is configured.

Example request​

curl --request POST \
  --url "https://acme.comind.work/api/w/HELPDESK/a/TICKET/tickets/list" \
  --header "Authorization: CMW_AUTH_CODE YOUR-TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"limitRecords": 10}'

OAuth (OIDC)​

For applications that need user-level authentication (e.g., MCP clients, IDE integrations), Comindwork supports OAuth 2.0 with PKCE:

  • Authorization endpoint: {your-instance}/.well-known/openid-configuration
  • Scope: openid profile email apiv2_ai
  • Flow: Authorization code with PKCE (public client, no client secret)
  • Token format: JWT validated via JWKS endpoint

OAuth tokens provide the same access as the authenticated user's account.

Integration users​

Inside Comindwork, API operations are attributed to the authenticated user. Best practice:

  • Create a dedicated "bot" user for each integration
  • Control the bot's name, avatar, access levels, and permissions through user administration
  • Use separate tokens for different integrations

TypeScript SDK​

The @comind/api npm package provides a typed client:

import { Comind } from "@comind/api";

const comind = new Comind();
comind.setLoadAccessToken();

const users = await comind.records.retrieve(
  "w/METAMETA/a/USER/tickets/list",
  { limitRecords: 100 }
);
console.log(`Found ${users.length} users`);

Install with:

npm install @comind/api

Request conventions​

  • Request and response bodies are JSON
  • Body size limit: 100 KB
  • Request timeout: 30 seconds
  • All string values in filters must be quoted: state="open", not state=open

Next steps​