Ijaz developer portal
What your technical team needs to read Ijaz data from your systems: a REST API, a Power BI connector, an MCP server, signed webhooks, and a guide to connecting through Zapier, Make and Power Automate.
Every connection is read-only: no key can change anything in Ijaz, and each key reads only the datasets it was given.
The API, the MCP server and webhooks are in Ijaz Enterprise; the Power BI connector in Ijaz Complete and Ijaz Enterprise. CSV and Excel downloads are in every plan.
Quick start
- In your Ijaz account: Settings → Data connections → Keys, create a key and choose the datasets it reads. The key shows once, so keep it somewhere safe.
- Send your first request with the command below; the latest mentions come back as JSON.
- To receive alerts as they happen, add your address under Settings → Data connections → Webhooks and choose the events.
curl -H "Authorization: Bearer $IJAZ_KEY" \ "https://ijaz.ai/api/v1/mentions?limit=20"
Authentication
Send the key in the header Authorization: Bearer <key>. The OData feed also accepts Basic authentication (the key as the password). Never put the key in a link or a web page.
curl -H "Authorization: Bearer $IJAZ_KEY" \ "https://ijaz.ai/api/v1/mentions?from=2026-10-01&to=2026-10-31&limit=100"
Limits
60 requests a minute and 10,000 a day per key. x-ratelimit-* headers on every answer, and retry-after with a 429.
REST
Each dataset at /api/v1/<dataset>, newest first. Parameters: from and to (YYYY-MM-DD in Riyadh time, or ISO 8601), limit (1 to 500, default 100), and cursor from next_cursor for the next page. The default is the last 90 days.
Example
GET https://ijaz.ai/api/v1/articles?from=2026-10-01&limit=2
{
"dataset": "articles",
"from": "2026-09-30T21:00:00.000Z",
"to": "2026-11-05T12:00:00.000Z",
"count": 2,
"has_more": true,
"next_cursor": "eyJ0IjoiMjAyNi0xMS0wNFQwOTowMDowMC4wMDBaIiwiaWQiOiIuLi4ifQ",
"data": [{ "id": "…", "published_at": "2026-11-04T09:00:00.000Z", "title": "…", "tier": 1, "tone": "negative", … }]
}Datasets and fields
/api/v1/mentions · Posts with tone
Every platform post that named the company or its competitors, with its tone as Ijaz read it or your team corrected it. own_account marks the official accounts' posts, which the dashboards do not count as mentions or in share of voice. OData: Mentions
| Field | Type |
|---|---|
| id | string |
| posted_at | datetime |
| platform | string |
| url | string |
| author_handle | string |
| author_name | string |
| author_followers | int |
| text | string |
| lang | string |
| subject | string |
| section | string |
| tone | string |
| tone_by | string |
| sarcasm | bool |
| aspects | json |
| likes | int |
| replies | int |
| shares | int |
| views | int |
| parent_text | string |
| own_account | bool |
/api/v1/articles · News
News stories that named the company or its competitors, with the outlet's tier and the tone. OData: Articles
| Field | Type |
|---|---|
| id | string |
| published_at | datetime |
| title | string |
| url | string |
| outlet | string |
| domain | string |
| lang | string |
| tier | int |
| tone | string |
| topic | string |
| subject | string |
| section | string |
/api/v1/stories · Stories and their level
The stories the alerts follow: their level now, the highest they reached, and their size. OData: Stories
| Field | Type |
|---|---|
| id | string |
| last_item_at | datetime |
| first_at | datetime |
| title_ar | string |
| title_en | string |
| kind | string |
| level | string |
| peak | string |
| status | string |
| items | int |
| negative | int |
| accounts | int |
| tier1_press | int |
| closed_at | datetime |
/api/v1/alerts · Alerts
The alerts' log: opened, raised, lowered, closed, notified. OData: AlertEvents
| Field | Type |
|---|---|
| id | string |
| at | datetime |
| story_id | string |
| title_ar | string |
| title_en | string |
| event | string |
| from_level | string |
| to_level | string |
/api/v1/reviews · Reviews
Google Maps reviews of the branches you follow, with the rating and the tone. OData: Reviews
| Field | Type |
|---|---|
| id | string |
| posted_at | datetime |
| branch | string |
| owner | string |
| competitor | string |
| rating | int |
| text | string |
| tone | string |
| url | string |
/api/v1/followers · Followers, day by day
Each followed account's follower count, as read each day. OData: FollowersDaily
| Field | Type |
|---|---|
| id | string |
| day | date |
| platform | string |
| handle | string |
| owner | string |
| competitor | string |
| label | string |
| followers | int |
OData (Power BI)
/api/v1/odata lists the tables and /api/v1/odata/$metadata describes them. Each table takes $top, $skip and $filter on its time field (ge, gt, le, lt). The default is the last year.
https://ijaz.ai/api/v1/odata https://ijaz.ai/api/v1/odata/$metadata https://ijaz.ai/api/v1/odata/Articles?$top=200&$filter=published_at ge 2026-10-01
MCP
POST /api/mcp with JSON-RPC. Tools: read each dataset by period, count and page cursor, and a summary tool for tone and levels.
| Tool | What it reads |
|---|---|
| list_mentions | Every platform post that named the company or its competitors, with its tone as Ijaz read it or your team corrected it. own_account marks the official accounts' posts, which the dashboards do not count as mentions or in share of voice. Fields: id, posted_at, platform, url, author_handle, author_name, author_followers, text, lang, subject, section, tone, tone_by, sarcasm, aspects, likes, replies, shares, views, parent_text, own_account. Newest first. |
| list_articles | News stories that named the company or its competitors, with the outlet's tier and the tone. Fields: id, published_at, title, url, outlet, domain, lang, tier, tone, topic, subject, section. Newest first. |
| list_stories | The stories the alerts follow: their level now, the highest they reached, and their size. Fields: id, last_item_at, first_at, title_ar, title_en, kind, level, peak, status, items, negative, accounts, tier1_press, closed_at. Newest first. |
| list_alert_events | The alerts' log: opened, raised, lowered, closed, notified. Fields: id, at, story_id, title_ar, title_en, event, from_level, to_level. Newest first. |
| list_reviews | Google Maps reviews of the branches you follow, with the rating and the tone. Fields: id, posted_at, branch, owner, competitor, rating, text, tone, url. Newest first. |
| list_followers_daily | Each followed account's follower count, as read each day. Fields: id, day, platform, handle, owner, competitor, label, followers. Newest first. |
| summary | Counts for the period: posts by tone, news by tier, open stories by level. Uses only the datasets the key may read. |
Adding it to AI tools
The MCP server works with tools that accept a server by address and an Authorization header, such as Claude Code, Cursor, VS Code and other developer tools.
URL: https://ijaz.ai/api/mcp
Header: Authorization: Bearer $IJAZ_KEY
curl -X POST "https://ijaz.ai/api/mcp" \
-H "Authorization: Bearer $IJAZ_KEY" -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_stories","arguments":{"limit":20}}}'Webhooks
A JSON POST with the headers ijaz-event, ijaz-delivery and ijaz-signature (t=<seconds>,v1=<HMAC-SHA256>). Compute the HMAC of "t.body" with your secret and compare, and reject anything older than 5 minutes. We retry after 1, 5 and 30 minutes, then 2, 6 and 24 hours.
Webhook events
| alert.opened | A new alert opened on a story |
| alert.escalated | An open alert's level rose |
| alert.notified | The recipients were told of an alert, by its level |
| report.ready | A report is ready |
| audit.log | A new line in the account's activity log |
An event's shape
POST https://your-system.example.com/ijaz
ijaz-event: alert.opened
ijaz-delivery: 3f0c…
ijaz-signature: t=1763380800,v1=5d2a…
{
"id": "…",
"type": "alert.opened",
"created_at": "2026-11-17T12:00:00.000Z",
"org_id": "…",
"company_id": "…",
"company": "…",
"data": { "company_id": "…", "company": "…", … }
}Verifying the signature (Node.js)
import crypto from "node:crypto";
// header: the ijaz-signature value, body: the raw request body (a string)
function verify(secret, header, body) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
const want = crypto.createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
const got = Buffer.from(parts.v1 ?? "");
return got.length === want.length && crypto.timingSafeEqual(Buffer.from(want), got);
}Connecting your systems through Zapier, Make and Power Automate
No code is needed to connect Ijaz to your CRM (Salesforce, HubSpot or Dynamics 365) or to Teams and Slack. These tools receive Ijaz's events or read its API, then take the next step in the system you choose.
Zapier
Receive events as they happen
- Create a Zap with the trigger Webhooks by Zapier → Catch Hook, and copy the address it gives you.
- In Ijaz: Settings → Data connections → Webhooks, paste the address, choose the events, then send a test event.
- Add the next step in Zapier: a task in Salesforce, a note on a HubSpot company, or a message in a Teams channel.
Read data on a schedule
- The trigger Schedule by Zapier at the interval you want.
- Then Webhooks by Zapier → GET on a dataset's address, such as
/api/v1/articles, with the headerAuthorization: Bearerand your key. - Then your system's step for each row.
Make
Receive events as they happen
- Create a scenario with the module Webhooks → Custom webhook, and copy the address.
- Paste it in Ijaz under Webhooks, choose the events, and send a test event so Make learns its shape.
- Add a Salesforce, HubSpot, Microsoft Dynamics 365 or Teams module after it.
Read data on a schedule
- Schedule the scenario at the interval you want.
- The module HTTP → Make a request, method GET, with the header
Authorization: Bearerand your key. - Then an Iterator over
datafor each row, and your system's module.
Power Automate
Receive events as they happen
- Create a flow with the trigger When a HTTP request is received, and save it to get its address.
- Paste it in Ijaz under Webhooks and choose the events.
- Add the action in Dynamics 365, Teams or SharePoint.
Read data on a schedule
- The trigger Recurrence.
- The action HTTP, method GET, with the header
Authorization: Bearerand your key. - Then Apply to each over
data.
- Keep the key in the tool's secrets, not in a step's text.
- Every event carries the
ijaz-signatureheader. Checking it is optional in these tools, and can be done with a code step in Zapier or Power Automate. - Webhook and HTTP steps may need a paid plan in the tool itself, under its terms.
- Text and names that reach your systems are yours to look after from then on, so keep them to those who need them.
Errors
401 invalid key, 402 the account is not active (cancelled, paused, trial or paid period ended), 403 outside the plan or the key's access, 404 no such dataset, 400 invalid parameter, 429 over the limit. Body: {"error":{"code","message"}}.
Keys and the account's status
A key works while the account is active. Once the account is cancelled or paused, or its trial or paid period ends, all its keys (REST, OData and MCP) stop with a 402 and the code billing, and work again when it is renewed. A group's key follows the group's contract.
Group keys
A group key reads either one company, chosen when it is created, or every group company: today's and any added later, which the group account manager confirms when creating it. Every row carries company_id and company, and ?company=<id> narrows a request to one company. When a company joins, its activity log records which group keys now read its data; when it leaves, the group's keys narrowed to it are revoked. Group webhooks receive every member company's events, each with company_id and company.
Versions
Changes to the API are written in «Ijaz updates» under «Developers». Version v1 never changes in a way that breaks what you built; a breaking change comes as a new version with fair notice. Ijaz updates
A question this page does not answer? Contact us