# Getting started with API

The Comind.work 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[​](#base-url "Direct link to Base URL")

All API requests are sent to your Comind.work 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[​](#endpoints-overview "Direct link to Endpoints overview")

| Endpoint                       | Method | Purpose                                                 |
| ------------------------------ | ------ | ------------------------------------------------------- |
| `/common`                      | GET    | Current user context (ID, name, timezone, admin status) |
| `/w/{WS}/a/{APP}/tickets/list` | POST   | List and filter records in a specific app               |
| `/tickets/list`                | POST   | List records across all workspaces                      |
| `/tickets/search`              | POST   | Full-text keyword search                                |
| `/tickets/history`             | POST   | Record change history with field diffs                  |
| `/tickets/multi`               | POST   | Create, update, or delete records (batch)               |
| `/schema/{WS}!{APP}`           | GET    | App schema (fields, lookups, actions, layouts)          |
| `/projects/{wksAlias}`         | GET    | Workspace info (apps, members, tabs)                    |
| `/download/{uuid}`             | GET    | Download a file or image attachment                     |

## Authentication[​](#authentication "Direct link to Authentication")

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

### Auth code (opaque token)[​](#auth-code-opaque-token "Direct link to 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)[​](#bearer-token-jwt "Direct link to Bearer token (JWT)")

```
Authorization: Bearer <jwt-token>
```

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

### Example request[​](#example-request "Direct link to 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)[​](#oauth-oidc "Direct link to OAuth (OIDC)")

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

* **Discovery endpoint:** `{your-instance}/.well-known/openid-configuration`
* **Authorization endpoint:** `{your-instance}/connect/authorize`
* **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[​](#integration-users "Direct link to Integration users")

Inside Comind.work, 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[​](#typescript-sdk "Direct link to 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-conventions "Direct link to Request conventions")

* Request and response bodies are JSON
* Request timeout: 30 seconds
* All string values in filters must be quoted: `state="open"`, not `state=open`

## Next steps[​](#next-steps "Direct link to Next steps")

* [Retrieving data](/api-integrations/rest-api/retrieving-data.md) - query records with filters, sorting, and pagination
* [Saving data](/api-integrations/rest-api/saving-data.md) - create, update, and delete records
* [Upload and save files](/api-integrations/rest-api/upload-and-save-files.md) - attach files to records
* [Rate limits, pagination, and errors](/api-integrations/rest-api/rate-limits-pagination-errors.md) - operational details