Provision Agent from URL

Kick off an asynchronous build that turns a creator’s channel URL (YouTube or Instagram) into a published, chat-ready agent. The request returns immediately with 202 Accepted and a buildId; you observe progress over Server-Sent Events, a polling snapshot, or an optional webhook. Once the build reaches ready, visitors chat with the agent over the anonymous chat endpoints.

This endpoint is authenticated with a brs_live_ API key — a server-side secret. NEVER ship the key to a browser. Your backend calls this endpoint and relays SSE/webhook events to the browser. The browser only ever calls the anonymous chat endpoints directly. See Authentication & rate limits.

Authentication

Header	Value	Required
`Authorization`	`Bearer brs_live_YOUR_KEY`	Yes
`Content-Type`	`application/json`	Yes
`Idempotency-Key`	`<uuid>`	Optional — dedups double-submits

The key is organization-scoped; all provisioned agents and their cost bill to that org. The required scope is agents:write. A key missing the scope returns 403 insufficient_scope. See Authentication & rate limits.

Request Body

string

required

A YouTube or Instagram channel URL (e.g. https://youtube.com/@channel or https://instagram.com/handle). Normalized and platform-detected server-side. An unsupported platform returns 400 unsupported_url.

string

A Cloudflare Turnstile token, verified server-side. Required when the platform has TURNSTILE_SECRET_KEY configured. A missing or invalid token returns 400 turnstile_failed.

string

default:"preview"

Ingestion mode.

preview (default) — bounded demo ingestion (~8 most-recent items, transcripts-only). Indexing finishes in seconds to about a minute.
full — full ingestion (deferred to a real signup; preview is the recommended path for landing-page / demo flows).

string

Optional agent intent (e.g. creator). Drives the default tool set selected for the agent.

string

Optional OpenRouter model id (e.g. openai/gpt-4o-mini). Defaults to the platform default model when omitted.

object

Optional delivery preferences.

Show deliver object

boolean

Set true to signal intent to open the SSE stream.

string

An HTTPS URL to receive out-of-band lifecycle events (at minimum the terminal event). Powers “email-me-a-link” UX without holding a connection. Payload is signed — see the Webhook reference.

Response — `202 Accepted`

string

Build identifier (bld_…). Use it to construct the stream and poll URLs.

string

queued for a fresh build, or ready immediately on a cache / handle-dedup hit (a fresh existing published agent for the same normalized handle is reused).

string

Present only when status is ready — the public slug to chat with.

string

Relative SSE URL: /v1/agents/builds/bld_…/events.

string

Relative snapshot URL: /v1/agents/builds/bld_….

Request / Response Examples

curl -i -X POST https://app.brainstormer.io/v1/agents:from-url \
  -H "Authorization: Bearer brs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d" \
  -d '{
    "url": "https://youtube.com/@channel",
    "turnstileToken": "0.aBcDeF...",
    "mode": "preview",
    "intent": "creator",
    "model": "openai/gpt-4o-mini",
    "deliver": { "stream": true, "webhookUrl": "https://yourapp.com/api/hook" }
  }'

import { randomUUID } from "node:crypto";

const res = await fetch("https://app.brainstormer.io/v1/agents:from-url", {
  method: "POST",
  headers: {
    Authorization: "Bearer brs_live_YOUR_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    url: "https://youtube.com/@channel",
    turnstileToken: turnstileToken, // from the browser, relayed to your backend
    mode: "preview",
    intent: "creator",
    model: "openai/gpt-4o-mini",
    deliver: { stream: true, webhookUrl: "https://yourapp.com/api/hook" },
  }),
});

if (!res.ok) throw new Error(`from-url failed: ${res.status}`);
const build = await res.json();
// build.buildId, build.status, build.streamUrl, build.pollUrl, build.agentSlug?

Response (202) — fresh build:

{
  "buildId": "bld_8c9d0e1f2a3b",
  "status": "queued",
  "streamUrl": "/v1/agents/builds/bld_8c9d0e1f2a3b/events",
  "pollUrl": "/v1/agents/builds/bld_8c9d0e1f2a3b"
}

Response (202) — instant cache / handle-dedup hit:

{
  "buildId": "bld_8c9d0e1f2a3b",
  "status": "ready",
  "agentSlug": "channel-creator-agent",
  "streamUrl": "/v1/agents/builds/bld_8c9d0e1f2a3b/events",
  "pollUrl": "/v1/agents/builds/bld_8c9d0e1f2a3b"
}

Behaviors

Turnstile is verified server-side; supply a fresh token per submit.
URL normalization + platform detection — youtube / instagram / unsupported. Unsupported platforms return 400 unsupported_url.
Handle dedup — a fresh existing published agent for the same normalized handle is reused and returned as ready instantly, with no new build and no new cost.
Idempotency — supplying Idempotency-Key makes a double-submit return the same build instead of spawning a second one.
Pre-flight failures (plan limit, insufficient credits) come back as a failed build event — observed over SSE / poll / webhook — not as a synchronous HTTP error on this request.

HTTP Status Codes

Status	Meaning
`202 Accepted`	Build queued (or returned `ready` on a dedup hit).
`400 unsupported_url`	URL is not a readable YouTube/Instagram channel.
`400 turnstile_failed`	Missing or invalid Turnstile token.
`401`	Missing or invalid `Authorization` header.
`403 insufficient_scope`	Key lacks the `agents:write` scope.
`429`	Rate limit hit (per-key or per-IP). Includes a `Retry-After` header (seconds).

Build Status & Error Model

The build progresses through a finite state machine. The complete ProvisioningStatus and ProvisioningErrorCode enums — with retryable semantics — are documented in the SSE reference and explained as concepts in Build lifecycle.

Getting Started

Agent Provisioning

Bot Service

Auth Service

Knowledge Service

Provision Agent from URL

Provision Agent from URL

Authentication

Request Body

Response — `202 Accepted`

Request / Response Examples

Behaviors

HTTP Status Codes

Build Status & Error Model

​Provision Agent from URL

​Authentication

​Request Body

​Response — 202 Accepted

​Request / Response Examples

​Behaviors

​HTTP Status Codes

​Build Status & Error Model

Provision Agent from URL

Authentication

Request Body

Response — `202 Accepted`

Request / Response Examples

Behaviors

HTTP Status Codes

Build Status & Error Model