Connect your systems to Marcomm AI

1. 1
   Apply for access

   Describe your system and pick the data you need. We review every application.

2. 2
   Create a key

   After approval, create a key in Settings, API. The key is shown once, so store it in your system.

3. 3
   Send a request

   Send the key in the Authorization header and call any endpoint below.

Example request

curl https://app.marcomm.works/api/v1/news/digest?days=7 \
  -H "Authorization: Bearer mc_live_..."

Send your key as a Bearer token with every request. A personal key acts as the person who created it, so it can read and decide approvals in that person's name. A workspace key is created by an admin and can only read. Keys can expire, can be limited to IP addresses, and can be rotated: the old key keeps working for 24 hours after a rotation.

Each key carries only the scopes your application was approved for.

news

News digest, articles and outlets.

crisis

Critical news and crisis incidents.

approvals

Pending approvals, and approving or rejecting them with a personal key.

content

Reading press releases and blog posts.

Every path starts with /api/v1. Read endpoints use GET and take query parameters. A response is JSON in the form {"data": ...}.

Send {"decision": "approve"} or {"decision": "reject", "comment": "..."} to the item. Rejecting needs a comment. The decision follows the same rules as the app and Slack, and it is recorded under the key owner. When the text contains phrases that need confirmation, you receive 409 confirmation_required with the warnings, and you can send the request again with "force": true.

curl -X POST https://app.marcomm.works/api/v1/approvals/press-releases/<id> \
  -H "Authorization: Bearer mc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"decision":"reject","comment":"Please fix the headline."}'

Limits are set per workspace, per minute and per day (UTC). Every response carries the headers below. Past a limit you receive 429 with Retry-After. To raise a limit, request an increase in Settings, API. Our team reviews it.

X-RateLimit-Limit

Requests allowed per minute.

X-RateLimit-Remaining

Requests left in the current minute.

X-RateLimit-Reset

Unix time when the minute window resets.

X-RateLimit-Day-Limit

Requests allowed per day.

X-RateLimit-Day-Remaining

Requests left today.

Retry-After

Seconds to wait before trying again. Only on 429.

Errors return JSON in the form {"error": {"code": ..., "message": ...}}.

Alerts, approval requests and the morning briefing can also be pushed to your system. Add a destination in Settings, API, Webhooks. Each request is JSON with the fields event (alert, approval or briefing), workspace, title, text, url, data and sentAt. An approval request carries data.kind (press_release, blog or event) and data.id, which you can use to read and decide through the API.

Each request is signed. Compute the HMAC-SHA256 of the raw request body with your signing secret and compare it to the X-Marcomm-Signature header, which has the form sha256=<hex>. Reject requests that do not match.

Verifying a webhook in Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

export function isFromMarcomm(rawBody: string, signature: string, secret: string) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}