Public API · v1

Harch Atelier REST API

Pull reputation intelligence, alerts, sentiment trends, and sanctions screening into your BI, CRM, and AI agents. Authenticate with a Bearer API key, get JSON back.

Authentication

All requests must include an Authorization header with a Bearer token prefixed by harch_:

Authorization: Bearer harch_<your-key>

API keys are scoped to the company of the user who created them. A key created by a user of Attijariwafa Bank can only read Attijariwafa Bank data — never another company's. Keys are hashed at rest (SHA-256); the plaintext is shown only once at creation time.

Don't have a key yet? Open the Enterprise Admin → API Keys tab to create one. Max 5 active keys per user.

Base URL & rate limits

All endpoints are relative to https://atelier.harchcorp.com. Example:

GET https://atelier.harchcorp.com/api/v1/alerts

Rate limit

60 req / min / key

Burst

120 req (10s)

Quota

10,000 req / month (Corporate)

Timeout

30s per request

Rate-limited responses return HTTP 429 with a Retry-After header. The X-Harch-Quota-Remaining header is sent on every successful response.

Endpoints

GET/api/v1/alerts

List alerts

Returns crisis alerts for the API key's company — negative-sentiment articles from the last 7 days plus high/critical risk assessments. Sorted by detectedAt descending.

Parameters

limitintegerMax alerts to return. Default 20, max 100.

sinceISO dateOnly alerts after this timestamp. Default: 7 days ago.

Example request

curl -H "Authorization: Bearer harch_your_key_here" \
     "https://atelier.harchcorp.com/api/v1/alerts"

GET/api/v1/reputation

Get reputation score

Returns the latest reputation score + pillar breakdown (sentiment, AI visibility, volume, authority, innovation, performance, purpose, share of voice) plus a 30-day history.

Example request

curl -H "Authorization: Bearer harch_your_key_here" \
     "https://atelier.harchcorp.com/api/v1/reputation"

GET/api/v1/sentiment

Get sentiment trend

Daily sentiment time-series for the API key's company. Each day reports the average sentiment score, article count, and positive/neutral/negative breakdown.

Parameters

rangestringTime window. One of 7d, 30d, 365d. Default 30d.

Example request

curl -H "Authorization: Bearer harch_your_key_here" \
     "https://atelier.harchcorp.com/api/v1/sentiment"

GET/api/v1/screen

Sanctions screening

Screens a name (individual, entity, or vessel) against the consolidated OFAC + EU + UN sanctions lists. Uses fuzzy matching with a configurable similarity threshold (default 0.86). Returns matches ranked by similarity.

Parameters

namestring *Entity / individual / vessel name to screen. 2-256 chars.

thresholdfloatSimilarity threshold 0.5-0.99. Default 0.86.

typestringPre-filter: individual | entity | vessel.

Example request

curl -H "Authorization: Bearer harch_your_key_here" \
     "https://atelier.harchcorp.com/api/v1/screen?name=Acme+Corp"

Errors

The API uses standard HTTP status codes. Error responses use a consistent JSON shape:

{
  "error": "Unauthorized",
  "message": "Missing or invalid API key. Pass it as Authorization: Bearer harch_<your-key>."
}

200Success.

400Bad request — missing or invalid query parameter.

401Unauthorized — missing or invalid API key.

403Forbidden — your key works but you don't have access to this resource.

404Not found — the resource or company does not exist.

429Too many requests — you hit the rate limit. Retry after the Retry-After header.

503Service unavailable — sanctions lists are cold-starting. Retry in 30s.

500Server error. If it persists, contact support with the request ID from X-Harch-Request-Id.

Webhooks

Register outbound webhooks to receive POST callbacks when critical alerts fire, reports become ready, or sanctions match. Manage your webhooks in the Enterprise Admin → Webhooks tab.

Every delivery is signed (if you set a secret) with X-Harch-Signature: hex(HMAC-SHA256(secret, body)). Failed deliveries retry up to 3 times with exponential backoff (2s → 4s → 8s).

Your receiver should:

Verify the signature (if you set a secret).
Respond with HTTP 2xx within 10 seconds.
Be idempotent — the same event may be delivered twice on retry.

alert.critical

Fires when a critical-severity article or risk assessment is detected for your company.

{
  "event": "alert.critical",
  "deliveredAt": "2026-07-31T09:00:00.000Z",
  "data": {
    "id": "clk2xyz...",
    "title": "OCP Group under scrutiny over ...",
    "severity": "critical",
    "source": "Le Matin",
    "url": "https://lematin.ma/...",
    "detectedAt": "2026-07-31T08:15:00.000Z",
    "sentimentScore": -0.72,
    "company": { "id": "clk1abc...", "name": "OCP Group", "slug": "ocp-group" }
  }
}

alert.high

Same as alert.critical but for high-severity alerts.

{
  "event": "alert.high",
  "deliveredAt": "2026-07-31T09:05:00.000Z",
  "data": { /* same shape as alert.critical */ }
}

report.ready

Fires when a new insight report PDF is generated for your company.

{
  "event": "report.ready",
  "deliveredAt": "2026-07-31T07:00:00.000Z",
  "data": {
    "reportId": "clk3rep...",
    "type": "risk",
    "period": "2026-07",
    "pdfUrl": "https://atelier.harchcorp.com/api/pdf/report/clk3rep.pdf"
  }
}

reputation.drop

Fires when the overall reputation score drops by 5+ points week-over-week.

{
  "event": "reputation.drop",
  "deliveredAt": "2026-07-31T06:00:00.000Z",
  "data": {
    "previousScore": 84.2,
    "currentScore": 78.1,
    "delta": -6.1,
    "company": { "id": "clk1abc...", "name": "Attijariwafa Bank", "slug": "attijariwafa-bank" }
  }
}

screening.match

Fires when a sanctions screening returns a match (similarity >= 0.86).

{
  "event": "screening.match",
  "deliveredAt": "2026-07-31T09:10:00.000Z",
  "data": {
    "query": "Acme Corp",
    "matches": [
      { "list": "OFAC", "name": "ACME CORPORATION", "similarity": 0.92 }
    ],
    "clean": false
  }
}

SDKs & client libraries

No official SDK yet — the REST API is stable and simple enough to call with fetch or requests. Join the waitlist for an official TypeScript SDK at api@harchcorp.com.

Public API · v1