Developers · Ingest API

Send anything in. Get a briefing out.

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

  • Hourly summaryRelease 2.4 shipped, checkout fix next
  • DevelopmentsRelease 2.4 Confirmed
  • Your briefingNext to your other sources
  • Your AI, over MCP and others
Sample data

Overview

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.

  1. 1

    Create a custom channel

    In the app: Channels, Custom (API). Pick chat or documents.

  2. 2

    Create an API key

    Profile, Account, API keys. It is shown once.

  3. 3

    POST your items

    One call, up to 50 items. Read the result in the next hourly summary.

Base URL
https://api.beegent.ai, HTTPS only
Format
JSON in and out, UTF-8
Errors
{"detail": "<message>"} with a meaningful status
Calls from
A backend, a script or an automation tool. Not a browser.
Versioning
Major version in the path (/ingest/v1). New optional fields are not a version change, so ignore fields you do not know. A breaking change gets a new path.
Status
Ingest v1 is live. No read API, pay-as-you-go or attachments yet. To read from AI tools, use the MCP server.

Authentication

An API key belongs to one Beegent user and acts for them. It reaches every custom channel of its owner, and nothing else.

Your API keyshown once

bgt_followed by 43 characters

bgt_ + 43 characters. Beegent stores only a SHA-256 hash, so a lost key cannot be recovered: revoke it and create another.

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}` }
  • Never in the URL. A key in the query string is ignored (the request gets 401) and URLs end up in logs. X-API-Key is not accepted either.
  • One key per integration. Keep it in that tool's secret store, so it can be revoked alone.
  • Revoking is instant. It takes effect on the next request.
  • Up to 10 active keys per user; the 11th is refused with 409. Scope: ingest.

Send messages

POST/ingest/v1/channels/{channel_id}/messages

Pick a channel kind

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.

chatapi_<12 hex>

Many short messages: Slack, support chats, alerts, CRM notes

50 items per request4,000 characters per item
documentsapi_docs_<12 hex>

Posts and articles: wiki pages, reports, newsletters

20 items per request50,000 characters per item

Request

HTTP
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"}
]}
FieldTypeRules
itemsrequiredarray1 to 50 (chat) or 1 to 20 (documents). Unknown top-level keys are ignored.
items[].textrequiredstringNot blank. At most 4,000 characters (chat) or 50,000 (documents), counted in characters, not bytes.
items[].idstring1 to 200 characters. Your own id, which makes retries safe (see Repeats).
items[].authorstringUp to 100 characters. Defaults to the key's name.
items[].titlestringUp to 300 characters. Heads a document as # title; kept as metadata on a chat channel.
items[].urlstringhttp or https, up to 2,000 characters. Becomes the source link that summaries cite.
items[].timestampstringWhen 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[].metadataobjectYour 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.

Response 200

Response
{"accepted": 1, "duplicates": 0, "units": 1, "units_left": 1240, "late": 0}
accepted
New items queued.
duplicates
Items skipped because their id was already sent to this channel.
units
Units this request used (0 for a request of only duplicates).
units_left
Free units left this month after this request.
late
Accepted items whose timestamp falls before the open summary window.

200 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.

Timestamps and late items

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.

In the next hourly summary, then your briefing and searchLate: stored, shown in the channel and found by search, but in no summary or briefing. Counted in late.

Repeats and the id field

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.

  • Ids are per channel: the same id on another channel is accepted there.
  • Matched exactly (case and spaces count) and remembered for at least 30 days.
  • An item without an id is never a repeat: sending it twice stores it twice.
  • Two requests that arrive together with the same new id store and bill it once.
  • After a 5xx or a timeout, resend with the same ids.

Limits and units

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.

  • A request reserves its units before anything is queued. If it needs more than are left, the whole request is refused with 402; smaller requests that fit, and requests of only duplicates, keep working.
  • Until pricing for extra usage arrives, 402 lasts until the 1st of the next month.
  • A request that fails after reserving (for example 503) gives its units back.
Items per request50 chat, 20 documents
text per item4,000 characters chat, 50,000 documents
id / author / title / url200 / 100 / 300 / 2,000 characters
Request body1 MB (1,048,576 bytes)
Request rate60 requests per minute per key, per clock minute
Monthly allowanceFree allowance per UTC calendar month
Active keys per user10

Errors

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.

Fix the request

Retrying it unchanged cannot work.

  • 400The body breaks a limit or the shape. The message names the field or the limit, for example items[2].text is over the limit of 4000 characters for a chat channel, or items[0] has unknown field(s): surprise.
  • 401No usable Authorization header (sent with WWW-Authenticate: Bearer). A key in the URL does not count.
  • 403Forbidden, one body for every reason on purpose: unknown or revoked key, a key without the ingest scope, a channel that is not one of the owner's active custom channels, or no active subscription. Check the key, the channel id and the account.
  • 413The body is over 1,048,576 bytes. Split the request.

Wait, or send less

Nothing was ingested.

  • 429More than 60 requests in the key's clock minute. Retry-After holds the seconds until the minute ends (1 to 60). Only requests with a valid key count, so wrong keys cannot lock the real one out.
  • 402The month's allowance cannot cover this request. The message says how many units were used and how many the request needs. Send fewer or smaller items, or wait for the 1st of the month.

Retry with the same ids

Nothing was billed.

  • 503The queue did not take the items. Retry after a short wait.
  • 5xxA 502 or 504 from the gateway, or a network timeout: treat it like 503.

Examples

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.

POST /ingest/v1/…/messages

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);

Zapier, Make and n8n

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.

JSON body
{"items": [{"id": "<source id>", "text": "<content>"}]}

Zapier

Webhooks by Zapier, Custom Request

  1. Use Custom Request, not the plain POST action: it cannot build the nested items array.
  2. Method POST, the URL above, Data: the JSON body with the trigger's fields inserted.
  3. Headers: Authorization = Bearer <key> and Content-Type = application/json. Keep the key as a fixed header value.

Make

HTTP, Make a request

  1. URL above, Method POST, the same two headers.
  2. Body type Raw, Content type JSON (application/json), the JSON body with fields mapped in.
  3. Enable Parse response and add an error handler that retries on 429 and 5xx.

n8n

HTTP Request node

  1. Method POST, the URL above, Authentication Generic credential type, Header Auth: Authorization = Bearer <key>.
  2. Send Body on, Body Content Type JSON, and an expression to send a batch (at most 50 or 20 items per call).
  3. Turn Retry On Fail on.
{{ { 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.

OpenAPI file

openapi-ingest-v1.yamlOpenAPI 3.1 description of ingest v1, for code generators and API clients.Download

Questions

Can I read my briefings or summaries through the API?

Not through this API: it only sends text in. For reading, connect your AI tool to the MCP server. A read API is planned.

Can I call it from a browser?

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.

Is it safe to retry a request?

Yes, if every item has a stable id. A repeated id on the same channel is dropped, counted as a duplicate and not billed.

What does it cost?

Every account gets a free monthly allowance. Pricing for extra usage is coming; until then a request past the allowance is refused with 402.

Send your first item.

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.