Barjeel API

Connect Barjeel to your case-management, HR, compliance and security systems. Manage subjects, groups, cases and evidence, run Intelligence and enrichment, review flags, read the audit trail and receive signed webhooks — all through one authenticated JSON API.

Overview

The Barjeel API is organized around REST resources. It accepts and returns JSON, uses standard HTTP methods and status codes, and authenticates with organization API keys. Everything an API key does happens inside its own organization and is recorded in the audit trail.

Base URL
https://app.barjeel.ai/api/public/v1
Transport
HTTPS only · JSON · Bearer keys
ResourceWhat you can do
IntelligenceRun an Intelligence search
SubjectsList subjects · Retrieve a subject · Create a subject · Update a subject · Delete a subject · Bulk import subjects · List relationships · Get a subject photo
GroupsList groups · Create a group · Rename a group · Delete a group · Change group members · Retrieve a group · List group members
CasesList cases · Retrieve a case · Create a case · Update a case · Delete a case
FilesList files · Retrieve a file · Upload a file · Create a download link
EnrichmentQueue enrichment · List enrichment jobs
Review flagsList open flags · Resolve a flag
AuditList audit events
AssistantAsk the Assistant · List conversations · Retrieve a conversation · Delete a conversation
LibraryList Library documents · Retrieve a Library document · Upload a Library document · Delete a Library document · Create a Library download link · Search the Library
ReportsList reports · Retrieve a report · Create a report · Update a report · Delete a report
AccountGet key usage
WebhooksList webhook endpoints · Create a webhook endpoint · Delete a webhook endpoint · Send a test event

Code samples on this page follow the language selected here:

Quickstart

  1. Ask Barjeel for an API key for your organization and tell us which permissions (scopes) it needs.
  2. Store the key in your server's secret manager as BARJEEL_API_KEY.
  3. Check it works by reading its usage:
Quickstart — cURL
curl --request GET 'https://app.barjeel.ai/api/public/v1/usage' \
  --header "Authorization: Bearer $BARJEEL_API_KEY"

  1. Create your first subject with POST /subjects, then subscribe to events with POST /webhooks.

Authentication & scopes

Send your key in the Authorization header on every request. Keys look like bjk_live_ followed by 48 hexadecimal characters.

Request headers
Authorization: Bearer <YOUR_BARJEEL_API_KEY>
Content-Type: application/json

Keep keys on your servers only — never in browser code, mobile apps, URLs or logs. If a key is exposed, ask for it to be revoked; revocation is immediate.

Each key carries scopes. A request without the required scope gets 403 forbidden. Grant each integration only what it needs.

ScopeAllows
intelligence:searchRun Intelligence searches (counts toward the monthly limit).
subjects:readList and read subjects and relationships (no photos).
subjects:photosRead subject photos (short-lived links). Requires subjects:read to find subjects.
subjects:writeCreate, update, delete and import subjects.
groups:readList and read groups and their members.
groups:writeCreate, rename and delete groups; add, move or remove members.
cases:readList and read cases and their links.
cases:writeCreate, update and delete cases and their links.
files:readList files, read classifications and create short-lived download links.
files:writeUpload files to cases.
enrichment:writeQueue enrichment and read enrichment jobs.
flags:readList items flagged for human review.
flags:writeResolve or dismiss flagged items.
audit:readRead the organization audit and custody trail.
assistant:useAsk the Assistant and read or delete API conversations (counts toward the Assistant allowance).
library:readList, search and download Library documents added through the API.
library:writeUpload and delete Library documents.
reports:readList and read reports created through the API.
reports:writeCreate, update and delete reports.
webhooks:manageRegister, list, test and delete webhook endpoints.

Actions taken with a key appear in your audit trail as api:<key prefix>. Keys can have an expiry date, and stop working when revoked, expired or when the organization is suspended.

Requests & responses

Send JSON bodies with Content-Type: application/json. IDs are UUIDs. Times are ISO 8601 in UTC. Unknown fields are ignored.

ShapeFormat
Single object{ "data": { … } }
List{ "data": [ … ], "has_more": false, "next_cursor": null }
Error{ "error": { "code": "not_found", "message": "…", "status": 404 } }

Subject references (SUB-…) are a readable form of the subject ID and can be used in the q filter. Successful creates return 201; queued work returns 202.

The API is versioned in the path. Additive changes (new fields, endpoints or events) can happen within v1, so ignore fields you do not recognize. Breaking changes will only ship in a new version, announced in the changelog. CORS is enabled, but keys must still never be used from a browser.

Pagination

List endpoints return up to limit items (default 50, maximum 200). When has_more is true, pass next_cursor as cursor to fetch the next page. Cursors are opaque; do not build them yourself.

Page through all subjects — TypeScript
async function* allSubjects(key: string) {
  let cursor: string | null = null;
  do {
    const url = new URL("https://app.barjeel.ai/api/public/v1/subjects");
    url.searchParams.set("limit", "200");
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
    if (res.status === 429) { await new Promise((r) => setTimeout(r, 60_000)); continue; }
    const page = await res.json();
    if (!res.ok) throw new Error(page.error.message);
    yield* page.data;
    cursor = page.next_cursor;
  } while (cursor);
}

Idempotency

Create operations marked "Supports Idempotency-Key" accept an Idempotency-Key header (8–100 characters). If a request is retried with the same key within 24 hours, the original response is returned with header Idempotent-Replayed: true and nothing is created twice. Reusing a key for a different request returns 409. Only successful responses are stored, so failed requests can be retried with the same key.

Rate limits & quotas

Each key may make 120 requests per minute across the API. Over the limit you receive 429 with Retry-After: 60. Intelligence searches also count toward the key's monthly limit (see GET /usage); failed upstream searches are not charged. Other operations have no monthly limit.

Retry 429, 500 and 502 responses with exponential backoff and jitter. Do not retry 400, 401, 403, 404 or 409 without changing the request.

Errors

StatusCodeMeaning and what to do
400invalid_requestThe request is malformed or a field is invalid. Fix it before retrying.
401invalid_api_keyThe key is missing, malformed, revoked or expired.
402quota_exceededA usage allowance is reached (monthly Intelligence limit, Assistant allowance or Library storage). Other operations still work.
403forbiddenThe key lacks the required scope, the organization is inactive, or the action is restricted.
404not_foundThe resource does not exist in your organization.
405method_not_allowedThe path exists but not with this HTTP method.
409conflictDuplicate name, or an Idempotency-Key reused with a different request.
413payload_too_largeThe upload exceeds 15 MB.
429rate_limitedMore than 120 requests per minute for this key. Back off and retry.
500server_errorThe operation could not be completed and nothing was reported as saved. Retry with backoff.
502upstream_unavailableIntelligence, Assistant or search services are temporarily unavailable. Not charged; retry later.

A 500 response means the change was not confirmed. Barjeel never reports a save as successful when it failed.

API reference

Loading…

Intelligence

POST/api/public/v1/intelligence/search

Run an Intelligence search. Searches open-source and archived intelligence for one identifier and returns normalized results.

Scope: intelligence:search

Subjects

GET/api/public/v1/subjects

List subjects. Returns subjects in your organization, newest first.

Scope: subjects:read

GET/api/public/v1/subjects/{id}

Retrieve a subject. Returns one subject with all stored fields (attributes).

Scope: subjects:read

POST/api/public/v1/subjects

Create a subject. Creates a subject.

Scope: subjects:write

PATCH/api/public/v1/subjects/{id}

Update a subject. Replaces the subject's attributes.

Scope: subjects:write

DELETE/api/public/v1/subjects/{id}

Delete a subject. Permanently deletes the subject, its files and its group memberships.

Scope: subjects:write

POST/api/public/v1/subjects/import

Bulk import subjects. Imports up to 250 rows per call, using the same column recognition as spreadsheet import.

Scope: subjects:write

GET/api/public/v1/subjects/{id}/relationships

List relationships. Returns explicit first-degree relationships recorded on imported data.

Scope: subjects:read

GET/api/public/v1/subjects/{id}/photo

Get a subject photo. Returns a short-lived link to the subject's photo.

Scope: subjects:photos

Groups

GET/api/public/v1/groups

List groups. Returns all groups in your organization.

Scope: groups:read

POST/api/public/v1/groups

Create a group. Creates a group.

Scope: groups:write

PATCH/api/public/v1/groups/{id}

Rename a group. Renames a group.

Scope: groups:write

DELETE/api/public/v1/groups/{id}

Delete a group. Deletes the group.

Scope: groups:write

POST/api/public/v1/groups/{id}/members

Change group members. Adds, moves or removes subjects in a group.

Scope: groups:write

GET/api/public/v1/groups/{id}

Retrieve a group. Returns one group with its member count.

Scope: groups:read

GET/api/public/v1/groups/{id}/members

List group members. Returns the subjects in a group (ID, reference and name).

Scope: groups:read

Cases

GET/api/public/v1/cases

List cases. Returns cases in your organization, newest first.

Scope: cases:read

GET/api/public/v1/cases/{id}

Retrieve a case. Returns a case with linked subjects (direct and through linked groups) and linked groups.

Scope: cases:read

POST/api/public/v1/cases

Create a case. Creates a case and links subjects and groups in one step.

Scope: cases:write

PATCH/api/public/v1/cases/{id}

Update a case. Updates name, description and links atomically.

Scope: cases:write

DELETE/api/public/v1/cases/{id}

Delete a case. Permanently deletes the case and its files.

Scope: cases:write

Files

GET/api/public/v1/files

List files. Returns files with their classification.

Scope: files:read

GET/api/public/v1/files/{id}

Retrieve a file. Returns one file's metadata and classification.

Scope: files:read

POST/api/public/v1/cases/{id}/files

Upload a file. Uploads a file to a case or subject; it is classified automatically.

Scope: files:write

POST/api/public/v1/files/{id}/download

Create a download link. Returns a short-lived download link.

Scope: files:read

Enrichment

POST/api/public/v1/enrichment

Queue enrichment. Queues background enrichment for subjects.

Scope: enrichment:write

GET/api/public/v1/enrichment/jobs

List enrichment jobs. Returns recent jobs, newest first.

Scope: enrichment:write

Review flags

GET/api/public/v1/flags

List open flags. Returns open items flagged for human review: irregular, unknown or misclassified files and data inconsistencies.

Scope: flags:read

POST/api/public/v1/flags/{id}/resolve

Resolve a flag. Marks a flag resolved or dismissed.

Scope: flags:write

Audit

GET/api/public/v1/audit

List audit events. Returns the organization's audit and custody trail, newest first.

Scope: audit:read

Assistant

POST/api/public/v1/assistant/messages

Ask the Assistant. Sends a message and returns the complete answer with its sources.

Scope: assistant:use

GET/api/public/v1/assistant/conversations

List conversations. Returns conversations started through the API, most recently active first.

Scope: assistant:use

GET/api/public/v1/assistant/conversations/{id}

Retrieve a conversation. Returns a conversation with all its messages in order.

Scope: assistant:use

DELETE/api/public/v1/assistant/conversations/{id}

Delete a conversation. Permanently deletes the conversation and its messages.

Scope: assistant:use

Library

GET/api/public/v1/library/files

List Library documents. Returns Library documents added through the API, newest first.

Scope: library:read

GET/api/public/v1/library/files/{id}

Retrieve a Library document. Returns one document's details and processing status.

Scope: library:read

POST/api/public/v1/library/files

Upload a Library document. Uploads reference material such as policies and procedures.

Scope: library:write

DELETE/api/public/v1/library/files/{id}

Delete a Library document. Permanently deletes the document and its search index.

Scope: library:write

POST/api/public/v1/library/files/{id}/download

Create a Library download link. Returns a short-lived download link.

Scope: library:read

POST/api/public/v1/library/search

Search the Library. Searches processed Library documents.

Scope: library:read

Reports

GET/api/public/v1/reports

List reports. Returns reports created through the API, most recently updated first (without content).

Scope: reports:read

GET/api/public/v1/reports/{id}

Retrieve a report. Returns a report including its HTML content.

Scope: reports:read

POST/api/public/v1/reports

Create a report. Creates a report.

Scope: reports:write

PATCH/api/public/v1/reports/{id}

Update a report. Changes the title, content or linked case.

Scope: reports:write

DELETE/api/public/v1/reports/{id}

Delete a report. Permanently deletes the report.

Scope: reports:write

Account

GET/api/public/v1/usage

Get key usage. Returns this key's scopes, monthly Intelligence usage and rate limit.

Scope: any key

Webhooks

GET/api/public/v1/webhooks

List webhook endpoints. Returns your organization's webhook endpoints.

Scope: webhooks:manage

POST/api/public/v1/webhooks

Create a webhook endpoint. Registers an HTTPS endpoint.

Scope: webhooks:manage

DELETE/api/public/v1/webhooks/{id}

Delete a webhook endpoint. Stops deliveries and deletes the endpoint.

Scope: webhooks:manage

POST/api/public/v1/webhooks/{id}/test

Send a test event. Queues a signed ping event to the endpoint; it is delivered within about a minute.

Scope: webhooks:manage

Webhooks

Webhooks push events to your HTTPS endpoint as they happen, so you don't need to poll. Register endpoints with POST /webhooks and store the whsec_… secret it returns — it is shown only once. Events triggered in the Barjeel app and through the API are both delivered.

Events

EventSent when
subject.createdA subject was created (app, import or API).
subject.updatedA subject's details were changed.
subject.deletedA subject was deleted.
case.createdA case was created.
case.updatedA case's details or links were changed.
case.deletedA case was deleted.
file.classifiedA file was uploaded and classified.
enrichment.completedBackground enrichment finished for a subject.
enrichment.failedBackground enrichment failed for a subject.
flag.raisedAn item was flagged for human review.
flag.resolvedA flagged item was resolved or dismissed.
library.file_uploadedA Library document was uploaded through the API.
report.createdA report was created through the API.
report.updatedA report was changed through the API.

Payload

Webhook payload
{
  "id": "4f3e2d1c-0b9a-4876-9543-210fedcba987",
  "type": "enrichment.completed",
  "created_at": "2026-11-20T08:00:00.000Z",
  "data": {
    "subject_id": "7c1e2a4b-0d3f-4b8e-9a51-2f6d8c0e1a23",
    "result_count": 4
  }
}

Payloads carry IDs only, never personal data. Fetch the resource with the API to read details.

Every delivery is signed with your endpoint secret (HMAC-SHA256). Signature verification code and the retry policy are in the Enterprise reference.

Changelog

DateChange
2026-11-22Added Assistant, Library and Reports endpoints; group detail and member listing; separate subjects:photos permission (photo_url is now only returned to keys with it, has_photo is always returned); key expiry dates.
2026-11-21REST API v1: subjects, groups, cases, files, enrichment, review flags, audit, usage and signed webhooks. Per-key scopes, cursor pagination, idempotency keys and a uniform error object.
2026-11-17Intelligence search at /api/public/gateway/v1/search (still supported).

Questions or need a scope added? Contact Barjeel