API_Docker_Gateway

Minimal first vertical slice for a token-authenticated gateway, now extended with a Grist integration framework.

Current slice

• HTTP endpoint: POST /api/v1/request
• API point: idea
• Actions: create, delete, move
• Required data fields: loaded from env (IDEA_REQUIRED_FIELDS)
• Auth: Bearer token or x-api-token
• Continuation: interactionId
• Downstream calls:
  • Grist integration framework added
  • Planka integration framework added
  • idea.create supports real live Grist and real live Planka card creation when enabled/configured
  • delete and move currently use the new framework but remain stubbed pending row/card-identification config

Run

cp .env.example .env
npm start

Default host/port:

• 127.0.0.1:8787

Default development token:

• dev-token
• override with GATEWAY_DEV_TOKEN

Token admin

• Open: http://127.0.0.1:8787/admin/tokens
• List tokens: GET /admin/api/tokens
• Generate token: POST /admin/api/tokens with JSON body like { "label": "Zapier" }
• Newly generated tokens are stored immediately and can be used against /api/v1/request right away.

Environment configuration

Important deploy-time values live in .env / Docker env:

• IDEA_REQUIRED_FIELDS
• GRIST_ENABLED
• GRIST_MODE
• GRIST_BASE_URL
• GRIST_API_KEY
• GRIST_DOC_ID
• GRIST_TABLE_ID
• GRIST_TITLE_FIELD
• GRIST_DATE_FIELD
• GRIST_MOVE_FIELD
• PLANKA_ENABLED
• PLANKA_MODE
• PLANKA_BASE_URL
• PLANKA_ACCESS_TOKEN
• PLANKA_BOARD_ID
• PLANKA_LIST_ID
• PLANKA_CARD_TYPE
• PLANKA_DUE_DATE_SOURCE
• PLANKA_POSITION

Live Grist mode

Set:

• GRIST_ENABLED=true
• GRIST_MODE=live
• GRIST_API_KEY, GRIST_DOC_ID, and GRIST_TABLE_ID

When live mode is enabled and configured, idea.create will POST a record to Grist using the configured title/date field mapping.

Live Planka mode

Set:

• PLANKA_ENABLED=true
• PLANKA_MODE=live
• PLANKA_BASE_URL, PLANKA_ACCESS_TOKEN, and PLANKA_LIST_ID

When live mode is enabled and configured, idea.create will also POST a card to Planka using the configured list id, card type, and position.

Docker

cp .env.example .env
cd docker
docker compose up --build

Example incomplete request

curl -s http://127.0.0.1:8787/api/v1/request \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer dev-token' \
  -d '{
    "apiPoint": "idea",
    "action": "create",
    "data": { "title": "Test idea" }
  }'

Example continuation

curl -s http://127.0.0.1:8787/api/v1/request \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer dev-token' \
  -d '{
    "apiPoint": "idea",
    "action": "create",
    "interactionId": "<from prior response>",
    "data": { "date": "2026-04-03" }
  }'

Example live Grist + Planka create

curl -s http://127.0.0.1:8787/api/v1/request \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer dev-token' \
  -d '{
    "apiPoint": "idea",
    "action": "create",
    "data": { "title": "Live Grist idea", "date": "2026-04-03" }
  }'

Test

npm test