Watch import API

Getting access

Integration is available to approved partners only. After approval you receive a partner id and API key. Submit an application using the form at the bottom of this page (not the general contact form).

Authentication

Every import request must be authenticated with your API key.

• Server-side POST — send Authorization: Bearer <apiKey>. Do not expose the API key in client-side HTML or JavaScript.
• Browser links (GET) — your server builds a signed URL using your partner id, API key, expiry, and payload (see Signed GET links). Users follow that link; the key never appears in the page source.

Unauthorized requests receive HTTP 401. Invalid payload returns 400.

End-to-end flow

1. Your site sends the user to LMKW with a watch payload (POST or signed GET).
2. If they do not have an LMKW account, they sign in with Google and return to the draft.
3. They see the pre-filled draft on Add watch, adjust it if needed, then save or dismiss it.

Base URL

API reference: https://letmeknowwhen.net/api
Import endpoint: https://letmeknowwhen.net/api/v1/watch-import

POST — JSON body

POST https://letmeknowwhen.net/api/v1/watch-import
Headers: Content-Type: application/json, Authorization: Bearer <apiKey>

{
  "queryText": "When is the next England vs France rugby match?",
  "tags": [
    "Sport",
    "Rugby",
    "England"
  ],
  "userContext": "Men's international test matches only.",
  "notify": true,
  "source": "Your Site Name"
}

queryText

Required. What the user wants to watch for (max 2000 characters).

tags

Optional. String array or comma-separated string (max 20 tags, 64 characters each).

userContext

Optional. Extra scope for LMKW’s observer (max 4000 characters).

notify

Optional. true (default) or false for news alerts.

source

Optional. Label shown on the draft screen (defaults to your partner name). Max 256 characters.

Signed GET links

For “Add to LMKW” buttons, generate links on your server. Compute sig = HMAC-SHA256(apiKey, partnerId + ":" + exp + ":" + canonical) (base64url output), where:

• partnerId — your partner id
• exp — Unix expiry time (links are rejected after this)
• canonical — the base64url data query value if you use one; otherwise the five fields q, tags, userContext, notify, and source joined with newlines in that order

https://letmeknowwhen.net/api/v1/watch-import?partner=YOUR_PARTNER_ID&exp=UNIX_SECONDS&data=BASE64URL_JSON&sig=SIGNATURE

POST response

{
  "ok": true,
  "needsLogin": false,
  "redirectUrl": "https://letmeknowwhen.net/events/new?fromImport=1"
}

If the user is not signed in to LMKW, needsLogin is true and redirectUrl sends them through Google sign-in first, then to the draft.

Cross-origin browser POST from your domain requires your origin to be registered for your partner account.

“Add Watch to LMKW” button

Use the LMKW elephant icon with tooltip text Add Watch to LMKW and a signed import URL as the link target:

Add Watch to LMKW

<!-- href must be a signed URL from your server — never put apiKey in HTML -->
<a href="SIGNED_IMPORT_URL" title="Add Watch to LMKW" rel="noopener">
  <img src="https://letmeknowwhen.net/icon_asset.png" alt="Add Watch to LMKW" width="48" height="48" decoding="async" />
</a>

Partner icon URL: https://letmeknowwhen.net/icon_asset.png

Limits & behaviour

• Import payloads are held in a signed session for up to one hour pending user action.
• Saved watches follow standard LMKW account limits and refinement.
• Questions about an existing application: use the partner application form below.