api_<12 hex>Many short messages: Slack, support chats, alerts, CRM notes
Developers · Ingest API
One HTTPS call puts your own text into a custom channel. From there it is summarized every hour, joins your briefing and search, and your AI can read it.
Your custom channel
chat or documents
The ingest API is write-only. You send items to a custom channel you created in the app, and it becomes a normal channel: stored, summarized hourly, rolled up into daily, weekly and monthly summaries, mined for developments, and included in your briefing and search.
In the app: Channels, Custom (API). Pick chat or documents.
Profile, Account, API keys. It is shown once.
One call, up to 50 items. Read the result in the next hourly summary.
https://api.beegent.ai, HTTPS only{"detail": "<message>"} with a meaningful status/ingest/v1). New optional fields are not a version change, so ignore fields you do not know. A breaking change gets a new path.An API key belongs to one Beegent user and acts for them. It reaches every custom channel of its owner, and nothing else.
bgt_followed by 43 characters
Send it on every request as a Bearer token. The scheme name is case-insensitive.
curl
-H "Authorization: Bearer $BEEGENT_KEY"Python
headers = {"Authorization": f"Bearer {os.environ['BEEGENT_KEY']}"}JavaScript
headers: { Authorization: `Bearer ${process.env.BEEGENT_KEY}` }401) and URLs end up in logs. X-API-Key is not accepted either.409. Scope: ingest.POST/ingest/v1/channels/{channel_id}/messages
Chosen when you create the channel; it cannot change. A custom channel takes one slot of your plan's channel limit (3, 10 or 25). Deleting it stops new pushes; what it stored stays.
api_<12 hex>Many short messages: Slack, support chats, alerts, CRM notes
api_docs_<12 hex>Posts and articles: wiki pages, reports, newsletters
POST https://api.beegent.ai/ingest/v1/channels/api_3f9c1a2b4d5e/messages
Authorization: Bearer bgt_...
Content-Type: application/json
{"items": [
{"id": "slack-1731490000.1234", "author": "maria", "text": "Release 2.4 is out", "url": "https://example.com/r/24"}
]}| Field | Type | Rules |
|---|---|---|
itemsrequired | array | 1 to 50 (chat) or 1 to 20 (documents). Unknown top-level keys are ignored. |
items[].textrequired | string | Not blank. At most 4,000 characters (chat) or 50,000 (documents), counted in characters, not bytes. |
items[].id | string | 1 to 200 characters. Your own id, which makes retries safe (see Repeats). |
items[].author | string | Up to 100 characters. Defaults to the key's name. |
items[].title | string | Up to 300 characters. Heads a document as # title; kept as metadata on a chat channel. |
items[].url | string | http or https, up to 2,000 characters. Becomes the source link that summaries cite. |
items[].timestamp | string | When the item happened: ISO 8601 with a UTC offset (2026-11-16T14:20:00Z or +02:00), from 30 days in the past to 5 minutes ahead. Stored in UTC. Without it the item gets its arrival time. |
items[].metadata | object | Your own key/value pairs, stored with the message and not shown to the summarizing model. Up to 20 keys of 1 to 40 letters, digits, _ . or -; values are a string (up to 500 characters), a number or a boolean. No nesting, no null. |
Any other field inside an item is refused with 400 naming the field. Items of one request keep their order.
{"accepted": 1, "duplicates": 0, "units": 1, "units_left": 1240, "late": 0}acceptedduplicatesunitsunits_leftlate200 means queued, not summarized. Items are stored within seconds and appear in the channel's next hourly summary, then in your briefing and search.
Accepted whole or refused whole. If one item is invalid, nothing is ingested and nothing is billed.
The hourly summarizer runs at five past each hour and reads the hour that just ended. An item without a timestamp gets its arrival time, so it lands in the next summary. An item with its own timestamp is stored under that time: inside the open window it is summarized normally; before it, its hour is already summarized, so the item is late. Late items are billed like any other. Importing dated history for summaries is not part of ingest v1.
late.Give every item a stable id from your system (a message id, a page id and version, a row id). The same id sent to the same channel again, from a retry or a second workflow, is dropped, counted in duplicates and not billed.
id on another channel is accepted there.id is never a repeat: sending it twice stores it twice.id store and bill it once.5xx or a timeout, resend with the same ids.Each new item costs units by length. Every account gets a free monthly allowance (per UTC calendar month); pricing for extra usage is coming.
ceil(characters / 2000), at least 1 per item. Repeats are free.
402; smaller requests that fit, and requests of only duplicates, keep working.402 lasts until the 1st of the next month.503) gives its units back.Every error body is {"detail": "..."}. The status tells you what to do. Checks run in this order: header, key, rate limit, channel and owner, body size, shape and limits, repeats, allowance, queue.
Retrying it unchanged cannot work.
Nothing was ingested.
Nothing was billed.
Keep the key in BEEGENT_KEY and the channel id in BEEGENT_CHANNEL. The Python and JavaScript versions follow the retry rules above. All three were run as written against a test backend.
curl
curl -sS -X POST "https://api.beegent.ai/ingest/v1/channels/$BEEGENT_CHANNEL/messages" \
-H "Authorization: Bearer $BEEGENT_KEY" \
-H "Content-Type: application/json" \
-d '{"items":[{"id":"deploy-9921","author":"deploy-bot","text":"Deploy 9921 finished: 0 errors"}]}'Python
import os, time, requests
URL = f"https://api.beegent.ai/ingest/v1/channels/{os.environ['BEEGENT_CHANNEL']}/messages"
HEADERS = {"Authorization": f"Bearer {os.environ['BEEGENT_KEY']}"}
def push(items, tries=5):
"""Send items (each with a stable "id"); returns the response dict."""
for attempt in range(tries):
try:
r = requests.post(URL, json={"items": items}, headers=HEADERS, timeout=30)
except requests.RequestException:
r = None # timeout or connection error: same ids make a retry safe
if r is not None and r.status_code == 200:
return r.json()
if r is not None and r.status_code == 429:
time.sleep(int(r.headers.get("Retry-After", "5")) + 1)
elif r is None or r.status_code >= 500:
time.sleep(2 ** attempt)
else: # 400, 401, 402, 403, 413: retrying the same request cannot help
raise RuntimeError(f"{r.status_code}: {r.json().get('detail')}")
raise RuntimeError("gave up after retries")
print(push([{"id": "ticket-4411", "author": "support", "text": "Customer reports slow checkout"}]))JavaScript
const url = `https://api.beegent.ai/ingest/v1/channels/${process.env.BEEGENT_CHANNEL}/messages`;
async function push(items) {
const res = await fetch(url, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BEEGENT_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ items }),
});
const body = await res.json();
if (!res.ok) {
const err = new Error(`${res.status}: ${body.detail}`);
err.status = res.status;
err.retryAfter = Number(res.headers.get("retry-after") || 0);
throw err; // retry 429 after err.retryAfter seconds and 5xx with the same ids; the rest cannot succeed unchanged
}
return body;
}
push([{ id: "pr-812", author: "ana", text: "PR 812 merged: new index on orders" }]).then(console.log);No code needed: any tool that can send an HTTP request can feed a channel. The shape is always the same: POST to https://api.beegent.ai/ingest/v1/channels/{channel_id}/messages, header Authorization: Bearer <key>, and a JSON body. Map the source record's own id into id, so a workflow that runs twice does not store twice.
{"items": [{"id": "<source id>", "text": "<content>"}]}Webhooks by Zapier, Custom Request
HTTP, Make a request
HTTP Request node
{{ { items: $input.all().map(i => ({ id: String(i.json.id), text: i.json.text })) } }}These recipes follow each tool's documentation and make the same request as the tested curl example; they have not yet been run on live Zapier, Make or n8n accounts.
Not through this API: it only sends text in. For reading, connect your AI tool to the MCP server. A read API is planned.
No. Call it from a backend, a script or an automation tool. Browsers are not supported, and a key put in page code is a leaked key.
Yes, if every item has a stable id. A repeated id on the same channel is dropped, counted as a duplicate and not billed.
Every account gets a free monthly allowance. Pricing for extra usage is coming; until then a request past the allowance is refused with 402.
Create a custom channel and an API key in the app, then make the call above.
Card required. One free trial per customer. Cancel any time.