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
| Resource | What you can do |
|---|---|
| Intelligence | Run an Intelligence search |
| Subjects | List subjects · Retrieve a subject · Create a subject · Update a subject · Delete a subject · Bulk import subjects · List relationships · Get a subject photo |
| Groups | List groups · Create a group · Rename a group · Delete a group · Change group members · Retrieve a group · List group members |
| Cases | List cases · Retrieve a case · Create a case · Update a case · Delete a case |
| Files | List files · Retrieve a file · Upload a file · Create a download link |
| Enrichment | Queue enrichment · List enrichment jobs |
| Review flags | List open flags · Resolve a flag |
| Audit | List audit events |
| Assistant | Ask the Assistant · List conversations · Retrieve a conversation · Delete a conversation |
| Library | List Library documents · Retrieve a Library document · Upload a Library document · Delete a Library document · Create a Library download link · Search the Library |
| Reports | List reports · Retrieve a report · Create a report · Update a report · Delete a report |
| Account | Get key usage |
| Webhooks | List 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
- Ask Barjeel for an API key for your organization and tell us which permissions (scopes) it needs.
- Store the key in your server's secret manager as
BARJEEL_API_KEY. - Check it works by reading its usage:
curl --request GET 'https://app.barjeel.ai/api/public/v1/usage' \
--header "Authorization: Bearer $BARJEEL_API_KEY"- 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.
Authorization: Bearer <YOUR_BARJEEL_API_KEY>
Content-Type: application/jsonKeep 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.
| Scope | Allows |
|---|---|
intelligence:search | Run Intelligence searches (counts toward the monthly limit). |
subjects:read | List and read subjects and relationships (no photos). |
subjects:photos | Read subject photos (short-lived links). Requires subjects:read to find subjects. |
subjects:write | Create, update, delete and import subjects. |
groups:read | List and read groups and their members. |
groups:write | Create, rename and delete groups; add, move or remove members. |
cases:read | List and read cases and their links. |
cases:write | Create, update and delete cases and their links. |
files:read | List files, read classifications and create short-lived download links. |
files:write | Upload files to cases. |
enrichment:write | Queue enrichment and read enrichment jobs. |
flags:read | List items flagged for human review. |
flags:write | Resolve or dismiss flagged items. |
audit:read | Read the organization audit and custody trail. |
assistant:use | Ask the Assistant and read or delete API conversations (counts toward the Assistant allowance). |
library:read | List, search and download Library documents added through the API. |
library:write | Upload and delete Library documents. |
reports:read | List and read reports created through the API. |
reports:write | Create, update and delete reports. |
webhooks:manage | Register, 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.
| Shape | Format |
|---|---|
| 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.
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
| Status | Code | Meaning and what to do |
|---|---|---|
400 | invalid_request | The request is malformed or a field is invalid. Fix it before retrying. |
401 | invalid_api_key | The key is missing, malformed, revoked or expired. |
402 | quota_exceeded | A usage allowance is reached (monthly Intelligence limit, Assistant allowance or Library storage). Other operations still work. |
403 | forbidden | The key lacks the required scope, the organization is inactive, or the action is restricted. |
404 | not_found | The resource does not exist in your organization. |
405 | method_not_allowed | The path exists but not with this HTTP method. |
409 | conflict | Duplicate name, or an Idempotency-Key reused with a different request. |
413 | payload_too_large | The upload exceeds 15 MB. |
429 | rate_limited | More than 120 requests per minute for this key. Back off and retry. |
500 | server_error | The operation could not be completed and nothing was reported as saved. Retry with backoff. |
502 | upstream_unavailable | Intelligence, 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
/api/public/v1/intelligence/searchRun an Intelligence search. Searches open-source and archived intelligence for one identifier and returns normalized results.
Scope: intelligence:search
Subjects
/api/public/v1/subjectsList subjects. Returns subjects in your organization, newest first.
Scope: subjects:read
/api/public/v1/subjects/{id}Retrieve a subject. Returns one subject with all stored fields (attributes).
Scope: subjects:read
/api/public/v1/subjectsCreate a subject. Creates a subject.
Scope: subjects:write
/api/public/v1/subjects/{id}Update a subject. Replaces the subject's attributes.
Scope: subjects:write
/api/public/v1/subjects/{id}Delete a subject. Permanently deletes the subject, its files and its group memberships.
Scope: subjects:write
/api/public/v1/subjects/importBulk import subjects. Imports up to 250 rows per call, using the same column recognition as spreadsheet import.
Scope: subjects:write
/api/public/v1/subjects/{id}/relationshipsList relationships. Returns explicit first-degree relationships recorded on imported data.
Scope: subjects:read
/api/public/v1/subjects/{id}/photoGet a subject photo. Returns a short-lived link to the subject's photo.
Scope: subjects:photos
Groups
/api/public/v1/groupsList groups. Returns all groups in your organization.
Scope: groups:read
/api/public/v1/groupsCreate a group. Creates a group.
Scope: groups:write
/api/public/v1/groups/{id}Rename a group. Renames a group.
Scope: groups:write
/api/public/v1/groups/{id}Delete a group. Deletes the group.
Scope: groups:write
/api/public/v1/groups/{id}/membersChange group members. Adds, moves or removes subjects in a group.
Scope: groups:write
/api/public/v1/groups/{id}Retrieve a group. Returns one group with its member count.
Scope: groups:read
/api/public/v1/groups/{id}/membersList group members. Returns the subjects in a group (ID, reference and name).
Scope: groups:read
Cases
/api/public/v1/casesList cases. Returns cases in your organization, newest first.
Scope: cases:read
/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
/api/public/v1/casesCreate a case. Creates a case and links subjects and groups in one step.
Scope: cases:write
/api/public/v1/cases/{id}Update a case. Updates name, description and links atomically.
Scope: cases:write
/api/public/v1/cases/{id}Delete a case. Permanently deletes the case and its files.
Scope: cases:write
Files
/api/public/v1/filesList files. Returns files with their classification.
Scope: files:read
/api/public/v1/files/{id}Retrieve a file. Returns one file's metadata and classification.
Scope: files:read
/api/public/v1/cases/{id}/filesUpload a file. Uploads a file to a case or subject; it is classified automatically.
Scope: files:write
/api/public/v1/files/{id}/downloadCreate a download link. Returns a short-lived download link.
Scope: files:read
Enrichment
/api/public/v1/enrichmentQueue enrichment. Queues background enrichment for subjects.
Scope: enrichment:write
/api/public/v1/enrichment/jobsList enrichment jobs. Returns recent jobs, newest first.
Scope: enrichment:write
Review flags
/api/public/v1/flagsList open flags. Returns open items flagged for human review: irregular, unknown or misclassified files and data inconsistencies.
Scope: flags:read
/api/public/v1/flags/{id}/resolveResolve a flag. Marks a flag resolved or dismissed.
Scope: flags:write
Audit
/api/public/v1/auditList audit events. Returns the organization's audit and custody trail, newest first.
Scope: audit:read
Assistant
/api/public/v1/assistant/messagesAsk the Assistant. Sends a message and returns the complete answer with its sources.
Scope: assistant:use
/api/public/v1/assistant/conversationsList conversations. Returns conversations started through the API, most recently active first.
Scope: assistant:use
/api/public/v1/assistant/conversations/{id}Retrieve a conversation. Returns a conversation with all its messages in order.
Scope: assistant:use
/api/public/v1/assistant/conversations/{id}Delete a conversation. Permanently deletes the conversation and its messages.
Scope: assistant:use
Library
/api/public/v1/library/filesList Library documents. Returns Library documents added through the API, newest first.
Scope: library:read
/api/public/v1/library/files/{id}Retrieve a Library document. Returns one document's details and processing status.
Scope: library:read
/api/public/v1/library/filesUpload a Library document. Uploads reference material such as policies and procedures.
Scope: library:write
/api/public/v1/library/files/{id}Delete a Library document. Permanently deletes the document and its search index.
Scope: library:write
/api/public/v1/library/files/{id}/downloadCreate a Library download link. Returns a short-lived download link.
Scope: library:read
/api/public/v1/library/searchSearch the Library. Searches processed Library documents.
Scope: library:read
Reports
/api/public/v1/reportsList reports. Returns reports created through the API, most recently updated first (without content).
Scope: reports:read
/api/public/v1/reports/{id}Retrieve a report. Returns a report including its HTML content.
Scope: reports:read
/api/public/v1/reportsCreate a report. Creates a report.
Scope: reports:write
/api/public/v1/reports/{id}Update a report. Changes the title, content or linked case.
Scope: reports:write
/api/public/v1/reports/{id}Delete a report. Permanently deletes the report.
Scope: reports:write
Account
/api/public/v1/usageGet key usage. Returns this key's scopes, monthly Intelligence usage and rate limit.
Scope: any key
Webhooks
/api/public/v1/webhooksList webhook endpoints. Returns your organization's webhook endpoints.
Scope: webhooks:manage
/api/public/v1/webhooksCreate a webhook endpoint. Registers an HTTPS endpoint.
Scope: webhooks:manage
/api/public/v1/webhooks/{id}Delete a webhook endpoint. Stops deliveries and deletes the endpoint.
Scope: webhooks:manage
/api/public/v1/webhooks/{id}/testSend 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
| Event | Sent when |
|---|---|
subject.created | A subject was created (app, import or API). |
subject.updated | A subject's details were changed. |
subject.deleted | A subject was deleted. |
case.created | A case was created. |
case.updated | A case's details or links were changed. |
case.deleted | A case was deleted. |
file.classified | A file was uploaded and classified. |
enrichment.completed | Background enrichment finished for a subject. |
enrichment.failed | Background enrichment failed for a subject. |
flag.raised | An item was flagged for human review. |
flag.resolved | A flagged item was resolved or dismissed. |
library.file_uploaded | A Library document was uploaded through the API. |
report.created | A report was created through the API. |
report.updated | A report was changed through the API. |
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
| Date | Change |
|---|---|
| 2026-11-22 | Added 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-21 | REST 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-17 | Intelligence search at /api/public/gateway/v1/search (still supported). |
Questions or need a scope added? Contact Barjeel
