> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Tulip

> Client-mode REST API connector for a curated Tulip MES slice: table records create/update/list and machine attribute report

Technical Preview

## Overview

A client-mode connector for a **curated MES** slice of the [Tulip public API](https://support.tulip.co/apidocs/), aligned to Hugo catalog **#136**:

| Catalog connector event | Path |
| - | - |
| POST tables/\{id}/records | `POST /api/v3/tables/{tableId}/records` |
| PUT tables/\{id}/records/\{rid} | `PUT /api/v3/tables/{tableId}/records/{recordId}` |
| POST attributes/reportMachineAttributes | `POST /api/v3/attributes/report` |
| GET tables/\{id}/records?filters= | `GET /api/v3/tables/{tableId}/records?limit=&filters=` |
| (smoke) list tables | `GET /api/v3/tables` |
| (smoke) get table | `GET /api/v3/tables/{tableId}` |
| (smoke) get record | `GET /api/v3/tables/{tableId}/records/{recordId}` |

`BASE_ADDRESS` is the instance root (`https://YOUR_INSTANCE.tulip.co`, no trailing slash). Topics use `mes/tulip/<object>/<verb>`. Interactive OpenAPI is also on each instance at `/apiDocs`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** HTTP **Basic** with a [Tulip API Token](https://support.tulip.co/docs/setting-up-a-tulip-api) — username = token **key**, password = token **secret**. Prefer Hub secrets (`TULIP_API_KEY` / `TULIP_API_SECRET`) or pass `Authorization: Basic {value.json.basic_b64}` on each MQTT payload. Never commit real tokens. Typical scopes: `tables:read`, `tables:write`, `attributes:report`.

> [!NOTE]
>
> For **global** API tokens, provide workspace context with path prefix `/api/v3/w/{workspaceId}/…` or header `X-Tulip-Workspace-ID`. Workspace-scoped tokens infer the workspace. The first workspace is often `DEFAULT`.

> [!NOTE]
>
> This template has **not** been verified against a live authenticated Tulip tenant. Status remains **blocked** until an authenticated live smoke succeeds (prefer GET `/api/v3/tables` → 200, then GET records → 200).

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Tulip (curated MES slice)
# Auth: HTTP Basic (API Token key:secret) via Basic {value.json.basic_b64}
#   or WITH USERNAME / WITH PASSWORD GET SECRET "TULIP_API_SECRET"
# BASE_ADDRESS: https://YOUR_INSTANCE.tulip.co

DEFINE ROUTE TulipRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_INSTANCE.tulip.co"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listtables
        WITH SOURCE_TOPIC "mes/tulip/tables/list"
        WITH DESTINATION_TOPIC "mes/tulip/tables/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v3/tables?limit={value.json.limit}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Createtablerecord
        WITH SOURCE_TOPIC "mes/tulip/tables/records/create"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{payload}"
    ADD EVENT Updatetablerecord
        WITH SOURCE_TOPIC "mes/tulip/tables/records/update"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records/{value.json.recordId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{payload}"
    ADD EVENT Listtablerecords
        WITH SOURCE_TOPIC "mes/tulip/tables/records/list"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records?limit={value.json.limit}&filters={value.json.filters}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Reportmachineattributes
        WITH SOURCE_TOPIC "mes/tulip/attributes/report"
        WITH DESTINATION_TOPIC "mes/tulip/attributes/report/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v3/attributes/report"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{payload}"
```

## MQTT payload examples

**List tables (smoke):**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "basic_b64": "<Base64(api_key:api_secret)>",
  "limit": "20"
}
```

**Create record** — publish body fields in `payload` (must include `id`):

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "basic_b64": "<Base64(api_key:api_secret)>",
  "tableId": "gthSX9t3tY2cJfBWe",
  "payload": "{\"id\":\"wo-1001\",\"status\":\"open\"}"
}
```

**Report machine attributes:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "basic_b64": "<Base64(api_key:api_secret)>",
  "payload": "{\"attributes\":[{\"machineId\":\"m1\",\"attributeId\":\"a1\",\"value\":42}]}"
}
```

## References

* [Tulip API introduction](https://support.tulip.co/apidocs/)
* [Table API guide](https://support.tulip.co/docs/table-api-guide)
* [Machine attributes API](https://support.tulip.co/docs/use-the-machine-attributes-api)
* [Set up a Tulip API Token](https://support.tulip.co/docs/setting-up-a-tulip-api)

## Template reference

Generated from the shipped broker template `tulip` (`-routeCode TULIP`). It lists every event the template defines.

### Auth

HTTP Basic (Tulip API Token key as username + secret as password). Prefer Hub secrets TULIP\_API\_KEY / TULIP\_API\_SECRET or Authorization: Basic \{value.json.basic\_b64}. Never commit real credentials. Scopes: tables:read, tables:write, attributes:report.

Auth headers used by the template: `Authorization: Basic {value.json.basic_b64}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Tulip connector | no |
| `BaseUrl` | string | Tulip base URL without trailing slash (e.g. [https://YOUR\_INSTANCE.tulip.co](https://YOUR_INSTANCE.tulip.co)) | yes |

`BASE_ADDRESS` default: `https://YOUR_INSTANCE.tulip.co`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listtables` | GET | `/api/v3/tables?limit={value.json.limit}` | `mes/tulip/tables/list` | `mes/tulip/tables/list/response` | `basic_b64`, `limit` |
| `Gettable` | GET | `/api/v3/tables/{value.json.tableId}` | `mes/tulip/tables/get` | `mes/tulip/tables/get/response` | `basic_b64`, `tableId` |
| `Listtablerecords` | GET | `/api/v3/tables/{value.json.tableId}/records?limit={value.json.limit}&filters={value.json.filters}` | `mes/tulip/tables/records/list` | `mes/tulip/tables/records/list/response` | `basic_b64`, `filters`, `limit`, `tableId` |
| `Createtablerecord` | POST | `/api/v3/tables/{value.json.tableId}/records` | `mes/tulip/tables/records/create` | `mes/tulip/tables/records/create/response` | `basic_b64`, `body`, `tableId` |
| `Gettablerecord` | GET | `/api/v3/tables/{value.json.tableId}/records/{value.json.recordId}` | `mes/tulip/tables/records/get` | `mes/tulip/tables/records/get/response` | `basic_b64`, `recordId`, `tableId` |
| `Updatetablerecord` | PUT | `/api/v3/tables/{value.json.tableId}/records/{value.json.recordId}` | `mes/tulip/tables/records/update` | `mes/tulip/tables/records/update/response` | `basic_b64`, `body`, `recordId`, `tableId` |
| `Reportmachineattributes` | POST | `/api/v3/attributes/report` | `mes/tulip/attributes/report` | `mes/tulip/attributes/report/response` | `basic_b64`, `body` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-routeCode TULIP"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ROUTE TulipRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_INSTANCE.tulip.co"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listtables
        WITH SOURCE_TOPIC "mes/tulip/tables/list"
        WITH DESTINATION_TOPIC "mes/tulip/tables/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v3/tables?limit={value.json.limit}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Gettable
        WITH SOURCE_TOPIC "mes/tulip/tables/get"
        WITH DESTINATION_TOPIC "mes/tulip/tables/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Listtablerecords
        WITH SOURCE_TOPIC "mes/tulip/tables/records/list"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records?limit={value.json.limit}&filters={value.json.filters}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Createtablerecord
        WITH SOURCE_TOPIC "mes/tulip/tables/records/create"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{value.json.body}"
    ADD EVENT Gettablerecord
        WITH SOURCE_TOPIC "mes/tulip/tables/records/get"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records/{value.json.recordId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Updatetablerecord
        WITH SOURCE_TOPIC "mes/tulip/tables/records/update"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records/{value.json.recordId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{value.json.body}"
    ADD EVENT Reportmachineattributes
        WITH SOURCE_TOPIC "mes/tulip/attributes/report"
        WITH DESTINATION_TOPIC "mes/tulip/attributes/report/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v3/attributes/report"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addRoute` (do not include `ADD METADATA`).

### Usage example

Call `Listtables` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'mes/tulip/tables/list/response' &
mosquitto_pub -t 'mes/tulip/tables/list' -m '{"basic_b64": "<basic_b64>", "limit": "<limit>"}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.