docs
// API Reference

Server-Side Tools

Tools the router runs itself, with no round-trip to your code. Research, artifacts, project intelligence, memory, and governed execution, all callable mid-completion. Each entry below carries its schema, latency profile, and billing footprint.

The tools fall into four categories:

  • Research, tools for gathering information from external sources.
  • Content, tools for creating and updating persistent artifacts.
  • Interaction, tools for requesting input from the user mid-stream.
  • Knowledge, tools for saving, recalling, and searching stored data.
  • Project Intelligence, tools for tracking decisions, milestones, relationships, and generating project briefings.

Tool Summary

ToolCategoryDescription
x_web_search Research Built-in web search
x_fetch_url Research Fetch and extract text from web pages and PDFs
x_code_search Research GitHub code search (snippet results)
x_repo_overview Research Full GitHub repository overview (metadata, languages, README, tree, recent commits)
x_repo_read Research Read specific files or directory listings from a GitHub repository
x_inspect_site Research Single-URL HTML and stylesheet inspection for theme, palette, and typography extraction
x_image_search Research Royalty-free and openly licensed image search; every result carries its license record
x_fetch_image Research Download one image search result's file, when its license permits a hosted copy
x_calculator Research Evaluate mathematical expressions safely
x_get_time Research The current time in UTC and in a time zone or place
x_get_weather Research A sourced weather report for a place: current conditions, 24 hours, 7 days
x_create_artifact Content Create persistent artifacts (code, docs, HTML, SVG, diagrams)
x_update_artifact Content Update a previously created artifact with new content
x_create_mockup Content Create a multi-file mockup bundle for visual preview in a sandboxed iframe (not offered in chat or through x_tools)
x_add_mockup_file Content Incrementally write one file at a time into a mockup bundle keyed by identifier (agentic-mode preferred path)
x_update_mockup Content Update files in a previously created mockup bundle
x_read_mockup Content Read mockup bundle contents (manifest, single file, or full inline). 256 KB cap on returned content.
x_read_artifact Content Read a single artifact's metadata and inline content (1 MiB cap; metadata-only above that). By identifier it reads the current chat's artifact (outside a chat, the workspace's), else the newest one you can read
x_list_artifacts Content List artifacts visible to the calling workspace (optionally filtered by chat and type)
x_generate_image Content Generate or edit images on the workspace's image generation endpoint; each image is stored as an artifact with its license record
x_ask_user Interaction Ask the user a clarifying question with optional structured input
x_propose_schedule Interaction Propose a scheduled task for the user to confirm on a card (chat only)
x_save_memory Knowledge Save facts, preferences, or instructions to per-workspace memory
x_recall_memory Knowledge Search saved memories using semantic similarity
x_forget Knowledge Retract a memory, decision, milestone, relation, or artifact created earlier in the session
x_workspace_search Knowledge Unified semantic search across workspace memories, documents, and artifacts
x_list_workspaces Knowledge Read-only list of the workspaces the caller can see, held to the API key's workspace allowlist when it has one
x_get_workspace Knowledge Read-only metadata of the workspace the request or chat is bound to
x_track_decision Project Intelligence Record structured architectural or design decisions
x_query_decisions Project Intelligence Search and filter recorded decisions, as markdown or JSON
x_track_milestone Project Intelligence Record project milestones and goals; with status, write a goal or a step of a plan before the work starts
x_update_milestone Project Intelligence Update one milestone: its title and description, its state (planned, in_progress, blocked, reached, abandoned), its order, its goal, its links to a memory, decisions and commits, and for a planned step its acceptance criteria and how it should be run
x_query_timeline Project Intelligence Query the project timeline of milestones
x_project_brief Project Intelligence Generate a project state briefing
x_relate Project Intelligence Create relationships between workspace entities
x_enhance_milestone Project Intelligence Propose a plan card's description or acceptance criteria from the card, its goal, its links and the project brief; nothing is saved
x_query_graph Project Intelligence Return the workspace knowledge graph (decisions + milestones + relations) as one composite payload
x_query_trace Project Intelligence Return the workspace's plan: each goal with its milestones in order, their states, which are ready to start, their acceptance criteria, the links between them, decisions, memories, commits and the agents that worked on them, as markdown or JSON; Erebine Desktop Code draws it as Trace and the plan board
x_analyze_workspace Project Intelligence Synthesize a structured brief of the workspace context (documents, memories, artifacts, chat history)
x_exec_invoke Execution Invoke a governed Erebine Execution Manager (EEM) tool via the MCP exec adapter; returns the invocation id for polling
x_exec_poll Execution Poll the lifecycle status of an exec invocation
x_exec_cancel Execution Cancel an in-flight exec invocation
x_exec_invoke_blocking Execution Long-lived blocking exec dispatch with streaming progress (MCP-only; 900s timeout)

Enabling Server-Side Tools

No server tool is on by default. The model is offered a server tool only when it is enabled: in chat through the workspace's agentic tool settings, and on the Responses API through the x_tools list on a web_search tool.

In Chat

Chat offers server tools on agentic turns. An owner or operator sets them in the Agentic workflows card under Behavior in workspace settings. Its Run chats through the agentic loop by default switch turns Agentic Workflows on by default for the workspace's chats, and its Default tools grid picks the tools the model is offered on an agentic turn. Each chat can switch Agentic Workflows on or off from the Tools list in its Model Options panel. With it on, the model is offered the Default tools. With it off, the chat's own Tool Groups become selectable: a turn runs the agentic loop with only the tools in the groups picked for it, not the Default tools, and a turn with no group picked is a plain completion. The Mockup group needs Agentic Workflows, so it is disabled while the switch is off. A deep research turn uses the research pipeline's own tool set either way; see Research Depth.

The grid groups the tools as follows:

  • Research: x_web_search, x_fetch_url, x_inspect_site, and x_image_search. x_web_search brings x_fetch_url with it, and x_image_search brings x_fetch_image.
  • Code: x_code_search, x_repo_overview, and x_repo_read.
  • Math: x_calculator.
  • Time and weather: x_get_time and x_get_weather. Both are on by default.
  • Workspace memory: x_save_memory, x_recall_memory, and x_workspace_search.
  • Workspace lookup: x_list_workspaces and x_get_workspace. Both are read-only. x_list_workspaces lists the workspaces the caller can see, held to the API key's workspace allowlist when it has one; x_get_workspace reads the chat's own workspace.
  • Project intelligence: x_track_decision, x_query_decisions, x_track_milestone, x_update_milestone, x_query_timeline, x_project_brief, x_query_graph, x_query_trace, x_relate, x_link_milestones, x_suggest_links, x_enhance_milestone, and x_analyze_workspace.
  • Artifacts: x_create_artifact, x_update_artifact, x_read_artifact, and x_list_artifacts.
  • Images: x_generate_image, available when the workspace has an image generation endpoint, and otherwise shown disabled with "No image generation endpoint is configured". It is on by default and switches x_generate_image for the workspace on every surface: chat, the Responses API and MCP. It does not govern the Responses API's hosted image_generation tool or the Images API. See x_generate_image.
  • Mockup: x_add_mockup_file and x_update_mockup, offered on agentic turns only.
  • Interactive: x_ask_user.

A tool stays unavailable in the grid until the workspace has the endpoints it needs: an inference endpoint for every tool except x_calculator, x_get_time, x_get_weather, x_ask_user and x_generate_image, plus an embedding endpoint for x_save_memory, x_recall_memory, x_workspace_search, and x_analyze_workspace. x_generate_image needs an image generation endpoint instead. x_image_search also needs an image library enabled on the deployment, and is otherwise shown disabled with "No image provider is configured". When the workspace has inference, embedding, and reranking endpoints, the switch is off, and no tool is selected, an owner or operator opening workspace settings turns the switch on with every available tool selected.

The grid has no entry for x_forget, x_create_mockup, x_research_run, x_research_run_result, or the x_exec_* tools, so chat does not offer them. x_read_mockup has no entry either: in a chat that already holds mockup bundles, the model is told it can call it to read a bundle before editing.

Chat Completions API

Server tools do not run on /v1/chat/completions. That surface builds its tool set strictly from your own tools array, so a request whose web_search_options carries server-tool intent (x_tools, x_agentic, x_analyst, search_context_size, or max_iterations) returns 400 with code unsupported_parameter and param: "web_search_options". Use the Responses API below, where the agentic loop runs. A bare web_search_options: {} with no fields is still accepted for OpenAI compatibility.

Responses API

Include a web_search tool in the tools array. The legacy web_search_preview and the dated web_search_2025_08_26 and web_search_preview_2025_03_11 work the same way. The OpenAI fields of the tool are covered under Web Search. The image_generation tool also runs, on the project's image generation endpoint. No other OpenAI hosted tool runs here: file_search, code_interpreter, computer, computer_use_preview, mcp, tool_search and programmatic_tool_calling return 400 unsupported_value; a namespace offers its functions to the model; and custom, local_shell, shell and apply_patch are echoed but not offered to the model. See Hosted Tools.

JSON
{ "model": "my-model", "input": "Find the latest research on transformer architectures", "stream": true, "tools": [ { "type": "web_search", "search_context_size": "medium", "x_tools": ["x_web_search", "x_fetch_url", "x_code_search"] } ] }

x_tools Selection

x_tools is selected on the Responses API web_search tool object. The selection rules below apply on that surface; the same array in a Chat Completions web_search_options block is rejected with 400 unsupported_parameter.

BehaviorDetails
Omitted or empty Defaults to ["x_web_search", "x_fetch_url"]. A web_search tool that sets x_agentic: true without x_analyst gets no server tools instead.
x_web_search included x_fetch_url is auto-included for URL follow-up.
Invalid names Silently ignored. Falls back to defaults if all are invalid.
x_code_search, x_repo_overview, x_repo_read Available when GitHub code search is enabled for your endpoint.
x_web_search Available when web search is enabled for your endpoint. Where no search backend is configured, requests for x_web_search are silently dropped.
x_image_search, x_fetch_image Available when image search is enabled for your endpoint; elsewhere both names are silently dropped. Neither implies x_web_search: list it too when the model should also search the web. See x_image_search.
x_generate_image Offered when the request is bound to a workspace whose Images switch is on, that has an image generation endpoint and that keeps generated content (not zero data retention), and the model can call tools; elsewhere the name is silently dropped. See x_generate_image.
x_calculator Available on every endpoint, and offered when listed. Evaluates mathematical expressions server-side.
x_add_mockup_file, x_update_mockup Offered only when the web_search tool also sets x_agentic: true and the request is bound to a chat. A mockup is written into a chat, so a request bound to none is not offered them.
x_create_mockup, x_read_mockup Not accepted. Either name is ignored like an invalid name.
Mockup functions in your own tools An x_create_mockup, x_add_mockup_file, or x_update_mockup function declared in the request's tools array is removed when the request is not bound to a chat, by the same rule.
x_list_workspaces, x_get_workspace Offered when listed. Read-only. x_list_workspaces returns only workspaces your API key's workspace allowlist permits; x_get_workspace reads the workspace the request is bound to.
x_ask_user Offered when listed. A call ends the turn with a function_call item for your client to answer; see x_ask_user.
x_exec_invoke, x_exec_poll, x_exec_cancel Offered when listed. x_exec_invoke_blocking runs only over MCP; see MCP Tools.

Commands

In the web chat and in desktop Chat, you can run a tool yourself. Type / at the start of the message field: the menu lists the commands under Erebine, each with what it takes and what it does. The arrow keys choose, Tab completes the word, and Enter completes it or, once it is typed, runs it. /decide, /milestone and /relate open a small form for their other fields, filled in from what you typed. A word that is not a command, such as a path, is sent as a message.

A command runs its tool at once, with no model in between. Typing it is your approval, so a write such as /remember or a web command such as /fetch runs without asking. The result shows as a card and joins the conversation: the model sees it on your next message. A command that cannot run in the chat is listed dimmed, with the reason, and one that does not run says why above the message field and keeps what you typed. In a zero-retention workspace the command runs and its card shows once, but nothing is kept and the model does not see it; the same holds when a reply starts in the chat while the command runs. A message sent while a command runs in the chat comes back to the message field with the reason; send it once the result lands. The iOS app shows command results in the chats it opens.

CommandRunsTakes
/briefx_project_briefAn optional focus
/decisionsx_query_decisionsAn optional query
/timelinex_query_timelineAn optional query
/graphx_query_graphNothing
/decidex_track_decisionA title; the form asks for the outcome and why
/milestonex_track_milestoneA title; the form asks what happened and its kind
/relatex_relateAn id; the form asks for the relationship and the other id
/recallx_recall_memoryA query
/searchx_workspace_searchA query
/rememberx_save_memoryThe fact to save
/artifactsx_list_artifactsNothing
/artifactx_read_artifactAn artifact id
/codex_code_searchA query
/repox_repo_overviewowner/name
/webx_web_searchA query
/fetchx_fetch_urlA URL
/inspectx_inspect_siteA URL
/imagesx_image_searchA query
/calcx_calculatorAn expression
/timex_get_timeAn optional place; without one, the time in UTC
/weatherx_get_weatherA place

Commands run in the chat's workspace. /web, /images, /code and /repo need web search, an image library or GitHub set up on the deployment. Desktop Code has the same commands; see Code.

Download Research

When a reply in the web chat, desktop Chat or the iOS app used the web research tools (x_web_search, x_fetch_url, x_inspect_site, x_image_search, x_fetch_image, a deep research turn, or /web, /fetch, /inspect and /images), it offers Download research once it finishes: in the message's actions, in the research panel's footer, and beside View Full Report on a deep research summary. The count beside it says how many pages it read. The action is not shown while the reply is still running. Anyone who can read the chat can download it; a shared link cannot.

Beside it, Schedule this turns the reply's question into a scheduled task that runs again on a schedule; each scheduled research run carries its own download.

The download is a zip of what the research gathered and the model was given, not the raw web responses:

FileHolds
index.mdHeaded with the run's title on a deep research turn; the question, the answer, the numbered sources with their titles, URLs and retrieval times, the sources the answer cites, the searches, the plan, and notes on anything cut or left out and why
report.mdThe full report, for a deep research turn
revisions/NN.mdEvery version of the answer, when a later research round or a revision request updated it: a header with revision, origin, round and change (and instruction, what was asked, on a revision request), then the answer as it was shown. index.md lists them and marks the current one
sources/NNN-<slug>.mdOne file per page read: a header with url, final_url, title, retrieved, tool, subtask, truncated and original_length, then the text the model was given
searches.jsonEvery search: the tool, the query, when it ran, its sub-task, and each result's title, URL and snippet
images.jsonEvery image result: its page, title, size, licence and credit
plan.jsonThe question, how the research ran, its timings and each pass's sub-tasks
claims.jsonClaims with their sources and confidence, conflicts and open questions, and the answer's citations
usage.jsonTokens per step and in total
manifest.jsonThe format's schema_version (1), the run's title on a deep research turn, revisions when the answer was updated, counts, sizes and what was cut

Images are listed, not copied: the zip holds no image files, only each image's page, licence and credit. A Pixabay result lists its page and not its file link, which expires.

The material is kept exactly as long as the reply: deleting the reply's branch or chat, the workspace or the project deletes it, and regenerating the reply replaces it. It is included in the data export and counts toward the project's storage allowance as Research on the Usage page, not toward the workspace's file limit. One reply keeps at most 32 MiB of page text; past that, pages are listed without their text and index.md says so. A zero-retention workspace keeps nothing and shows no download.

Replies from before this feature have no stored research and show no download.

Humanize Output

Humanize Output is a workspace policy, not an LLM-callable tool. Every assistant turn produced for a chat in that workspace runs through a deterministic post-synthesis filter before the content is flushed to the chat bubble and persisted. The filter strips AI tells (sycophantic openers, marketing adjectives, em-dash spam, redundant scaffolding, hedge filler) while preserving code, file paths, URLs, numbers, math, and citation markers byte-identical.

The filter is server-side and chat-page-scoped. External SDKs calling /v1/chat/completions directly do not pass through it; only chats rendered in the Erebine chat-page UI invoke it.

How it works

Six pipeline stages. Each stage either pass-through or safe-abort; if any invariant trips, the original assistant draft is returned byte-identical and the abort is logged at .notice with the precise reason.

  1. Protect-zone tokenizer. Masks code fences, inline code, URLs, file paths, numeric literals, math expressions, and citation tokens behind opaque sentinels so later stages cannot rewrite them.
  2. Deterministic scrub. Site-ordered rule engine applies ~32 named rules covering openers, wrap-ups, banned phrases, marketing adjectives, transitional cliches, em-dash discipline, header demotion, and tricolon flattening.
  3. Optional LLM polish. When the workspace's humanize_polish_enabled is on and the scrubbed draft is over 120 characters, sends the text to the workspace's configured polish endpoint (defaults to the workspace small endpoint) with a strict rewrite prompt. Failure (timeout, non-200, parse error) falls through to the next stage with the scrubbed draft; polish never blocks an assistant turn.
  4. Post-polish re-scrub. Runs the same rule engine again. Polish models occasionally reintroduce tells; the scrubber is the floor.
  5. Safety net. Aborts and returns the original draft if any sentinel went missing or got duplicated, any banned floor phrase survived, or the masked-text length changed by more than 40% (with a 32-character minimum-length floor).
  6. Unmask. Replaces every sentinel with its original protected span.

Enabling the policy

Open the chat workspace settings tab and find the Humanize output card under Workspace behaviour. The main switch turns the deterministic scrub on or off for every chat in the workspace. A sub-card exposes:

  • LLM polish: when on, the polish pass runs after the deterministic scrub. Higher quality, adds ~1-3 s latency per turn.
  • Polish endpoint: the workspace endpoint the polish call targets. Defaults to workspace-small (auto), which selects the same small/cheap endpoint chat-name generation uses.
  • Voice anchor: a per-workspace textarea that conditions the polish system prompt on a custom voice register (see below).

Per-chat override

Each chat carries a tri-state override chip in the model-options panel: Inherit | On | Off. Inherit defers to the workspace toggle; On and Off force the filter for that single chat regardless of the workspace setting. Use Off when humanization is interfering with a precise technical answer.

Voice anchoring

The platform ships a built-in default voice block compiled into the frontend service. When the polish sub-toggle is on, the polish system prompt is conditioned on that voice register as "Match this voice: ...". This is what turns "less AI-sounding" into "sounds like this project."

The chat-settings Voice anchor textarea pre-populates from the built-in default when the workspace has not stored an override. Three states are honored:

  • Override set (non-empty): the text is sent verbatim as the voice line. Use this to give one workspace a distinct register without affecting others.
  • Override set (empty): explicit opt-out. The polish prompt omits the voice line entirely for this workspace.
  • No override (default): the built-in default voice block is used. Clear the textarea and save to enter the opt-out state; re-saving the seeded default text installs it as an explicit override.

Notes and limitations:

  • The built-in default lives in compiled code, not on disk. Operators who need to change the platform-wide default ship a new frontend release; operators who need a per-workspace variation use the textarea.
  • The voice block is injected only when the LLM polish sub-toggle is on. The deterministic scrub runs regardless and does not read the voice block.
  • The polish prompt budgets roughly 800 characters for the voice line; longer overrides are passed through and may cost extra prompt tokens.

What is preserved verbatim

The protect-zone tokenizer ensures the following spans pass through every stage byte-identical. If any sentinel is missing or duplicated after polish, the safety net aborts and returns the original draft.

  • Fenced code blocks (triple backtick)
  • Inline code (single backtick)
  • Markdown links and bare URLs (http, https, ws, wss, file)
  • Absolute and relative file paths
  • Numeric literals (integers, floats, hex, scientific notation, percentages)
  • Math expressions ($...$ and $$...$$)
  • Citation tokens like [^1]

Operator visibility

A small humanized chip marks assistant bubbles whose content went through the filter. The chat owner always sees it; the workspace-level Show humanized chip toggle, off by default, shows it to everyone else, for visual confirmation during QA. Hovering the chip shows whether the message was "scrub only" or "scrub + polish".

Admin observability

Platform administrators see the filter's activity on the Humanize tab of the admin chat dashboard:

  • Turns per stage (scrub, polish, aborted, skipped).
  • Aborts per reason (missing_sentinel, duplicated_sentinel, banned_phrase_floor, length_delta, polish_timeout, polish_error).
  • The rules that fire most often.
  • Polish-stage latency at P50 and P95.

Audit trail

A humanized assistant message keeps the draft it replaced; a message the filter did not run on keeps none. The chat owner can select the message's humanized chip to compare the draft with the delivered text.

x_fetch_url

Fetches and extracts readable text content from web pages and PDF documents. Supports single-URL fetch, parallel multi-URL fetch, link discovery for site exploration, and automatic same-domain link following.

Parameters

ParameterTypeDescription
urlrequired string A single URL to fetch content from. Must be http or https.
urlsoptional string[] Multiple URLs to fetch in parallel (max 5). Use this OR url, not both. When both are provided, they are merged and deduplicated.
discover_linksoptional boolean Extract links from fetched pages for site exploration. Default: false.

Modes

  • Single URL, provide only url without discovery flags. Returns extracted plain text directly.
  • Multi-URL, provide urls array for parallel fetching. Returns a JSON object with a pages array, each containing url, content, and error fields.
  • Discovery, set discover_links: true to extract links from fetched pages.

SSRF Protection

All URL fetches are protected against Server-Side Request Forgery (SSRF). Requests to private and internal IP ranges are blocked: 10.x, 172.16-31.x, 192.168.x, 127.x, ::1, fe80::/10, 169.254.x.x.

Character Budget

Multi-URL fetches share a total budget of 24,000 characters, distributed equally across all successfully fetched pages. Pages exceeding their share are truncated.

Use Cases

  • Reading documentation pages in full
  • Extracting article content for summarization
  • Crawling related pages on the same domain
  • Fetching PDF text content

Example: Single Fetch

JSON
{ "name": "x_fetch_url", "arguments": { "url": "https://docs.example.com/api/authentication" } }

Example: Multi-Fetch with Discovery

JSON
{ "name": "x_fetch_url", "arguments": { "urls": [ "https://docs.example.com/guide/getting-started", "https://docs.example.com/guide/configuration" ], "discover_links": true } }

Example Multi-Fetch Response

JSON
{ "discover_links_enabled": true, "total_pages": 4, "pages": [ { "url": "https://docs.example.com/guide/getting-started", "content": "Getting Started. Install the SDK with npm install...", "error": false, "discovered_links": [ {"url": "https://docs.example.com/guide/authentication", "text": "Authentication"}, {"url": "https://docs.example.com/guide/advanced", "text": "Advanced Usage"} ] }, { "url": "https://docs.example.com/guide/configuration", "content": "Configuration. Set environment variables to customize...", "error": false, "discovered_links": [] }, { "url": "https://docs.example.com/guide/authentication", "content": "Authentication. Use API keys or OAuth2 tokens...", "error": false, "followed_from_discovery": true }, { "url": "https://docs.example.com/guide/advanced", "content": "Advanced Usage. Configure retry policies and timeouts...", "error": false, "followed_from_discovery": true } ] }

SSE Event

SSE
data: {"type":"x_research.reading","name":"x_fetch_url","arguments":"{\"url\":\"https://docs.example.com/api/authentication\"}"}

x_repo_overview

Returns a full GitHub repository overview: metadata, language breakdown, README content, top-level directory tree, and recent commits. Use this first to discover repository structure before reading individual files with x_repo_read.

Parameters

ParameterTypeDescription
repositoryrequired string GitHub repository. Accepts owner/repo or a full URL (e.g. https://github.com/owner/repo).

Example

JSON
{ "name": "x_repo_overview", "arguments": { "repository": "vapor/vapor" } }

x_repo_read

Reads specific files or directory listings from a GitHub repository. Use x_repo_overview first to discover the structure, then x_repo_read to fetch the files you need.

Parameters

ParameterTypeDescription
repositoryrequired string GitHub repository. Accepts owner/repo or a full URL.
pathoptional string Single file or directory path to fetch.
pathsoptional string[] Multiple file or directory paths to fetch in one call.

Example

JSON
{ "name": "x_repo_read", "arguments": { "repository": "apple/swift-nio", "paths": ["Sources/NIOCore/Channel.swift", "Sources/NIOCore/EventLoop.swift"] } }

x_research_run

Vendor extension. Not part of the OpenAI tool catalog. Erebine addition.

Runs a deep multi-phase research pipeline on a query. The pipeline decomposes the question into sub-tasks, crawls supplied URLs, produces a synthesis report, extracts evidence and memories, and emits project-intelligence candidates. Use it for questions that need multi-source synthesis, root-cause investigation, or a broad review. It is expensive: a run takes minutes and consumes hundreds of thousands of tokens, so do not use it for single-fact lookups.

By default the call blocks until the report is ready. Pass async: true to start the run in the background and return a run_id immediately; collect the result later with x_research_run_result.

Parameters

ParameterTypeDescription
queryrequired string The question to research.
verbosityoptional string Output depth. One of: concise, standard (default), detailed.
scopeoptional string Where to pull evidence from. One of: auto (default), local (workspace documents and memories), web, mixed.
modeoptional string Forces the research mode instead of auto-detecting it from the query. One of: target_focused (analyze a specific URL, product, or company), exploratory (broad topic research).
asyncoptional boolean Run as a background job and return immediately with a run_id instead of blocking. Poll or cancel with x_research_run_result. Defaults to false.

Example

JSON
{ "name": "x_research_run", "arguments": { "query": "Compare the leading approaches to quantum error correction in 2026", "verbosity": "detailed", "scope": "web" } }

Result

A blocking call returns the run id, the run's title, a synthesis preview, artifact and memory identifiers, any project-intelligence entries created, and pipeline stats (subtasks_run, urls_crawled, tokens_input, tokens_output, duration_ms, halted_on_budget). The research watchdog now stops a run on inactivity or elapsed time rather than a credit budget, so halted_on_budget is retained for compatibility and generally reports false. An async call returns {"run_id":"...","status":"running"}.

x_research_run_result

Vendor extension. Not part of the OpenAI tool catalog. Erebine addition.

Polls or cancels an async research run started with x_research_run and async: true. Pass the run_id you received from that call. Only runs owned by your own project resolve; any other id returns not_found.

Parameters

ParameterTypeDescription
run_idrequired string The run id returned by x_research_run with async: true.
canceloptional boolean Cancel the run instead of polling it. Defaults to false.

Result

While the run is in progress the result carries {"status":"running","phase":...}. When it finishes the result carries status completed with the full research result, failed with an error, or cancelled. An unknown or foreign run id resolves to not_found; a malformed run_id is an error.

Example

JSON
{ "name": "x_research_run_result", "arguments": { "run_id": "a1b2c3d4-0000-4000-8000-000000000000" } }

x_inspect_site

Single-URL HTML and stylesheet inspection for extracting site theme metadata: palette, typography, structure, and key element classes. Use when the model needs to mirror a reference design rather than crawl multiple pages.

Parameters

ParameterTypeDescription
urlrequired string The page URL to inspect.

x_fetch_image

Downloads one x_image_search result's file together with its license record. Name the result by provider and provider_id. The router looks the license and the file URL up itself, from its search cache or from the library, so the caller cannot supply or alter either. A result whose can_host_copy is false is never downloaded: for Unsplash the call registers the use its guidelines require and answers the URL to embed, and for any other library it is refused with the license record and the reason.

Opt in by listing x_fetch_image in x_tools beside x_image_search. Over MCP the tool is erebine.research.fetch_image.

Parameters

ParameterTypeDescription
providerrequired string The provider field of the search result.
provider_idrequired string The provider_id field of the same result, copied exactly. Checked against the library's id format before use.
sizeoptional string full (default) downloads the full_url rendition; preview the preview_url rendition. A full file over 20 MB, 16384 px a side or 50 MP is not downloaded: the preview is returned in its place, url stays the full file, and attachment_note says why.

Delivery

SurfaceWhat comes back
MCP A text content block with the JSON below (file_attached: true), then the file as an MCP image content block: base64 data and mimeType. A file over 3.75 MB (5 MB as base64, the per-image limit of common MCP clients) is not attached: the preview rendition is attached in its place when it fits (attached_rendition: "preview"), else nothing is, and attachment_note says which.
Responses API The JSON only, with file_attached: false. The file bytes never reach the model or the response.

Download Limits

  • https only, with the same SSRF protection as x_fetch_url: private and internal addresses are blocked, and each redirect (at most 5) is checked again.
  • 20 MB per file.
  • PNG, JPEG, GIF or WebP, at most 50 megapixels and 16,384 px on a side. Anything else is refused.
  • The file is delivered as the library serves it; sha256 is the digest of those bytes.

Response Format

The body carries the same license fields as an x_image_search result, beside these:

FieldTypeDescription
provider, provider_id string The result the file belongs to.
url string The URL the file was, or would have been, fetched from.
mime_type string The MIME type read from the file's bytes.
width, height integer The file's pixel size.
bytes integer The file's size in bytes.
sha256 string Lowercase hex SHA-256 of the file.
file_attached boolean Whether the file follows as an MCP image content block.
attached_rendition string MCP only: full or preview, the rendition attached. Absent when nothing is attached.
attachment_note string Why the attached or downloaded file is not the full-size file: it was over the attachment limit, or over the download or pixel limits so the preview was fetched in its place. Absent otherwise.
use_reported boolean Unsplash only: whether the use was registered with Unsplash.
error string Why the file was not downloaded. Present only on a refusal or failure, which is a tool error.

Example Tool Call (generated by model)

JSON
{ "name": "x_fetch_image", "arguments": { "provider": "pexels", "provider_id": "1234567" } }

Example Response

JSON
{ "attribution_required": false, "attribution_site": "Pexels", "attribution_site_url": "https://www.pexels.com", "attribution_text": "Photo by Jane Doe on Pexels", "attribution_url": "https://www.pexels.com/photo/brisket-1234567/", "bytes": 2483117, "can_host_copy": true, "commercial_use": true, "file_attached": true, "height": 3000, "hotlink_allowed": true, "license_code": "pexels", "license_name": "Pexels License", "license_url": "https://www.pexels.com/license/", "mime_type": "image/jpeg", "photographer": "Jane Doe", "provider": "pexels", "provider_id": "1234567", "sha256": "3f8a1c0d9e7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a19", "source_page": "https://www.pexels.com/photo/brisket-1234567/", "url": "https://images.pexels.com/photos/1234567/pexels-photo-1234567.jpeg", "width": 4000 }

Example Use Report (Unsplash)

A result that may not be copied is never downloaded. For Unsplash the call registers the use its guidelines require and answers the URL to embed.

JSON
{ "attribution_required": true, "attribution_site": "Unsplash", "attribution_site_url": "https://unsplash.com/?utm_source=erebine&utm_medium=referral", "attribution_text": "Photo by Sam Lee on Unsplash", "attribution_url": "https://unsplash.com/@samlee?utm_source=erebine&utm_medium=referral", "can_host_copy": false, "commercial_use": true, "file_attached": false, "hosting_restriction": "The Unsplash API guidelines require the image to be hotlinked from the Unsplash CDN (full_url), so a self-hosted copy is not permitted.", "hotlink_allowed": true, "license_code": "unsplash", "license_name": "Unsplash License", "license_url": "https://unsplash.com/license", "photographer": "Sam Lee", "provider": "unsplash", "provider_id": "Ab3dEf9GhIj", "source_page": "https://unsplash.com/photos/Ab3dEf9GhIj?utm_source=erebine&utm_medium=referral", "url": "https://images.unsplash.com/photo-1600000000000-0a1b2c3d4e5f", "use_reported": true }

x_generate_image

Generates images from a description, or edits and composes new ones from images you already have, on the workspace's image generation endpoint. Each image is stored as an artifact with its license record, the same record an x_image_search result carries. The model never sees image bytes. How many images a call may make, whether it takes references, its sizes and the steps it runs come from the endpoint model's image generation settings.

SurfaceHow it is offered
Chat Offered on every turn when the workspace has an image generation endpoint, its Images switch is on (the default), it keeps generated content, and the chat model can call tools. References are the images in the conversation, and each image is shown with the answer.
Responses API List x_generate_image in the web_search tool's x_tools. The request must be bound to a workspace (the X-Workspace-Id header or a workspace-prefixed route) whose Images switch is on, that has an image generation endpoint and that keeps generated content, and the model must be able to call tools.
MCP erebine.artifact.generate_image. Needs an API key with the research scope, a workspace whose Images switch is on, and a workspace image generation endpoint. Calls draw on the project's research rate limit.

Workspace owners and operators turn image generation off for a workspace with the Images entry of its default tools (see Enabling Server-Side Tools). Switched off, the tool is offered nowhere, and a call that reaches it anyway returns a plain result, "Image generation is turned off for this workspace.", that the model can pass on.

Parameters

ParameterTypeDescription
promptrequired string A full visual description: subject, setting, composition, style and lighting.
aspectoptional string square (default, 1:1), landscape (3:2), portrait (2:3) or wide (2:1). A model with a fixed list of sizes renders the listed size closest to the aspect; any other renders 1024x1024, 1536x1024, 1024x1536 or 2048x1024 when its size limits allow it, else its default size.
referencesoptional string[] Images to edit or compose from. In chat, the conversation's image handles (img_1, ...); on the Responses API and MCP, artifact ids (cart_...) of images in the same workspace. An id that names no image you can read in the workspace is refused. A model that takes no reference images generates from the prompt alone and says so in notes.
countoptional integer How many variations to make, default 1. Capped at what the model makes per call; notes says when it was. Offered only when the model makes more than one image per call.

The workspace's model sets the limits: how many images a call makes and whether, and how many, reference images it takes. On the Responses API the tool definition the model sees carries those limits; over MCP the schema lists the widest, and notes says what a call changed.

Screening, Retention and Billing

  • On a shared endpoint every prompt is screened first (see Image Prompt Screening). Reference images are not screened. A refused prompt, or one that could not be screened, returns no image and a plain result, not an error: refused, retry and reason say why, on every surface alike.
  • While the image engine is busy with other renders, a call waits its turn. A call still waiting shortly before its time limit returns no image and the same plain result, with retry: true and, in reason, how many other image requests the engine holds.
  • A workspace with zero data retention keeps no generated content, so the tool is not offered there and a call that reaches it is refused.
  • Each call is billed like an Images API request, to the project, at the image generation endpoint: in chat attributed to the member who sent the turn, on the Responses API and MCP to the member the API key belongs to. A call that makes no image is not billed for one.

Delivery

SurfaceWhat comes back
Chat The JSON below without url; each image is shown with the answer.
Responses API The JSON below. Each image is a workspace artifact, and url downloads it for 60 minutes, like an Images API url response.
MCP A text content block with the JSON, then one image content block per image. A PNG over 3.75 MB (5 MB as base64, the per-image limit of common MCP clients) is attached downscaled; an image that cannot be brought under the limit is not attached. attached_rendition and attachment_note say which, and url keeps the full-size file.

Response Format

Each entry of images carries the license fields of an x_image_search result, beside these:

FieldTypeDescription
artifact_id string The stored artifact. Pass it in references to edit the image later.
width, height, mime_type integer, string The image's pixel size and type.
url, url_expires_at string, integer Responses API and MCP only: a signed download link, valid for 60 minutes, and when it expires (Unix seconds). It needs no API key. Absent when no link could be made; the artifact is still stored and notes says so.
attached_rendition, attachment_note string MCP only: full or downscaled, and why the attached image is not the full file, or why none is attached. Absent when no image is attached.

The body also carries model, aspect, size, references, notes (only when something changed) and display.

Example Tool Call (generated by model)

JSON
{ "name": "x_generate_image", "arguments": { "prompt": "A jar of wildflower honey on a weathered picnic table, golden hour, shallow depth of field", "aspect": "landscape" } }

Example Response (Responses API)

JSON
{ "aspect": "landscape", "display": "Each image is stored in this workspace as artifact_id. Its url downloads the full-size file until url_expires_at (60 minutes); hand on the url or the artifact_id, never image data.", "images": [ { "artifact_id": "cart_7k2m9p4q1r8s3t6v0w5x", "attribution_required": false, "attribution_text": "Generated with FLUX.2-klein-4B", "attribution_url": "https://www.apache.org/licenses/LICENSE-2.0", "can_host_copy": true, "commercial_use": true, "height": 1024, "hotlink_allowed": true, "license_code": "apache-2.0", "license_name": "Apache-2.0", "license_url": "https://www.apache.org/licenses/LICENSE-2.0", "mime_type": "image/png", "source_page": "https://www.apache.org/licenses/LICENSE-2.0", "url": "https://api.erebine.ai/v1/images/content/eyJhbGciOiJIUzI1NiJ9...", "url_expires_at": 1793001600, "width": 1536 } ], "model": "FLUX.2-klein-4B", "references": [], "size": "1536x1024" }

x_calculator

Evaluates mathematical expressions server-side using a safe recursive-descent parser. No code execution, only arithmetic, functions, and constants are supported.

Parameters

ParameterTypeDescription
expressionrequired string Mathematical expression to evaluate. Maximum 1,000 characters.

Supported Operations

CategorySupported
Operators + - * / ^
Functions sqrt, log, ln, sin, cos, tan, abs, floor, ceil, round, min, max
Constants pi, e

Use Cases

  • Unit conversions and dimensional analysis
  • Financial calculations (compound interest, amortization)
  • Scientific computation (trigonometry, logarithms)
  • Quick arithmetic the model should not hallucinate

Example Tool Call

JSON
{ "name": "x_calculator", "arguments": { "expression": "10000 * (1 + 0.05)^3" } }

Example Response

JSON
{ "expression": "10000 * (1 + 0.05)^3", "result": 11576.25 }

More Examples

ExpressionResult
sqrt(144) + 2^320.0
sin(pi/2)1.0
log(1000)3.0
max(42, 17) * min(3, 5)126.0
abs(-273.15) + ceil(2.1)276.15

SSE Event

SSE
data: {"type":"x_research.calculating","name":"x_calculator","arguments":"{\"expression\":\"10000 * (1 + 0.05)^3\"}"}

x_get_time

Tells the time in UTC and in a time zone or place, from the server's clock and the IANA time zone database. Daylight saving and half-hour or 45-minute offsets are applied exactly. A zone name needs no lookup; a place is looked up first. Every answer carries the UTC instant beside the local one, so a wrong zone is easy to spot.

Parameters

ParameterTypeDescription
time_zoneoptional string IANA zone name, such as Asia/Tokyo. Abbreviations such as EST are refused, because several zones share them. Takes precedence over place.
placeoptional string A place name, such as Kyoto or Austin, Texas. At most 200 characters.
atoptional string An ISO 8601 instant with Z or an offset, converted instead of now.

With no argument the answer is UTC only. A place in a country with one time zone takes that zone. In the United States the zone comes from the National Weather Service for that point. Elsewhere in a country with several zones, the zone whose reference city is nearest is used and the answer marks it approximate.

Example Response

JSON
{ "clock": "router", "instant": "now", "place": {"country": "Japan", "country_code": "JP", "latitude": 35.0115754, "longitude": 135.7681441, "name": "Kyoto", "region": "Kyoto Prefecture"}, "sources": [{"attribution": "Place data from OpenStreetMap contributors (ODbL)", "name": "OpenStreetMap Nominatim", "role": "geocoding", "url": "https://www.openstreetmap.org/copyright"}], "summary": "It is 03:20 on Sunday, 15 November 2026 in Kyoto, Kyoto Prefecture, Japan (Asia/Tokyo, UTC+09:00). In UTC it is 18:20 on Saturday, 14 November 2026.", "utc": "2026-11-14T18:20:00Z", "zone": {"basis": "country", "daylight_saving": false, "local": "2026-11-15T03:20:00+09:00", "name": "Asia/Tokyo", "utc_offset": "+09:00", "utc_offset_seconds": 32400, "weekday": "Sunday"} }

Errors

A failed call returns error and error_type: invalid_arguments, unknown_time_zone, place_not_found, ambiguous_place (with candidates to ask the user about), geocoder_unavailable or zone_undetermined. The tool never guesses a place.

x_get_weather

Reports the weather for a place: current conditions, the next 24 hours and the next 7 days, from public meteorological services. One call answers a question that web search answers poorly, with sourced figures.

Parameters

ParameterTypeDescription
placeoptional string A place name. Give place, or both latitude and longitude.
latitudeoptional number Degrees north, -90 to 90.
longitudeoptional number Degrees east, -180 to 180.
unitsoptional string metric (C, km/h, mm, hPa) or imperial (F, mph, in, inHg). Defaults to imperial in the United States and its territories, metric elsewhere.
includeoptional array Any of current, hourly and daily. Defaults to all three.

Report

FieldContents
locationName, region, country, coordinates, IANA time zone and local time.
currentTemperature, feels-like, humidity, dew point, wind speed, gusts and direction, precipitation, cloud cover, pressure, clear-sky UV index and a plain condition, where the source provides them. These are the source's forecast for the current hour, not a station observation.
todayHigh, low, condition, precipitation, sunrise and sunset.
hourlyThe next 24 hours.
dailyUp to 7 days after today, each with high, low, condition, precipitation, sunrise and sunset.
alertsOfficial alerts in effect, in the United States. Elsewhere alerts_note says no official alert source is checked.
sourcesEach data source used, with the credit its terms ask for.
summaryOne line.

Sources

Forecasts come from MET Norway, worldwide. In the United States the National Weather Service forecast is also read: it stands in when MET Norway does not answer, a disagreement of 3 C or more in the current temperature is noted rather than averaged, and its official alerts are reported. Places are looked up with OpenStreetMap. Only the place or the coordinates are sent to these services. Answers are cached briefly, as each service's terms ask.

Credit the data when you show it: "Data from MET Norway" (CC BY 4.0), "Data from the US National Weather Service", and "Place data from OpenStreetMap contributors" (ODbL). The sources field carries the text and link for each.

Example Tool Call

JSON
{ "name": "x_get_weather", "arguments": { "place": "Kyoto", "include": ["current"] } }

Example Response

JSON
{ "alerts_note": "No official alert source is checked for this location; absence of alerts here means nothing.", "current": {"as_of": "2026-11-15T03:00:00+09:00", "basis": "MET Norway forecast for the current hour, not a station observation", "cloud_cover_percent": 100, "condition": "rain", "dew_point": 13.5, "feels_like": 13.3, "humidity_percent": 96.9, "issued_at": "2026-11-15T02:19:31+09:00", "precipitation_next_hour": 0.8, "pressure": 1014.9, "temperature": 13.9, "uv_index_clear_sky": 0, "wind_direction": "NE", "wind_direction_degrees": 49.5, "wind_speed": 4.7}, "location": {"country": "Japan", "country_code": "JP", "latitude": 35.01, "local_time": "2026-11-15T03:20:00+09:00", "longitude": 135.77, "name": "Kyoto", "query": "Kyoto", "region": "Kyoto Prefecture", "time_zone": "Asia/Tokyo"}, "notes": ["Today's high and low cover the hours from now to local midnight."], "sources": [ {"attribution": "Place data from OpenStreetMap contributors (ODbL)", "name": "OpenStreetMap Nominatim", "role": "geocoding", "url": "https://www.openstreetmap.org/copyright"}, {"attribution": "Data from MET Norway (CC BY 4.0)", "name": "MET Norway", "role": "primary", "url": "https://api.met.no/"} ], "summary": "Kyoto, Kyoto Prefecture, Japan: 13.9 C, rain, wind 4.7 km/h NE. Today 15.8 / 13.8 C.", "today": {"condition": "heavy rain", "date": "2026-11-15", "high": 15.8, "low": 13.8, "precipitation": 29.7, "sunrise": "06:30", "sunset": "16:52", "weekday": "Sunday"}, "units": {"precipitation": "mm", "pressure": "hPa", "system": "metric", "temperature": "C", "wind": "km/h"} }

Errors

A failed call returns error and error_type: invalid_arguments, place_not_found, ambiguous_place (with candidates), geocoder_unavailable, or no_source_answered (with sources_failed). The tool never invents a figure; a value no source gave is left out.

x_create_artifact

Creates a persistent artifact such as a code file, document, HTML page, SVG image, or Mermaid diagram. Artifacts are stored in the chat and can be viewed, downloaded, and updated. It is offered when enabled: in chat through the Artifacts group of the workspace's Default tools, and on the Responses API through x_tools; see Enabling Server-Side Tools.

Parameters

ParameterTypeDescription
identifierrequired string Stable slug for this artifact. 1-128 characters, ASCII alphanumeric, hyphens, underscores, and dots only. Used to reference the artifact for later updates.
titlerequired string Human-readable display title for the artifact.
typerequired string MIME content type for the artifact content.
languageoptional string Programming language for syntax highlighting (e.g. python, swift, javascript). Omit for non-code artifacts.
contentrequired string The full content of the artifact. Maximum 1 MB.

Supported MIME Types

MIME TypeUse For
text/markdownMarkdown documents, reports, notes
text/htmlHTML pages, interactive previews
text/plainPlain text files, configuration
image/svg+xmlSVG vector graphics
text/x-mermaidMermaid diagram definitions
application/jsonJSON data files
text/x-{language}Code files (e.g. text/x-python, text/x-swift)

Identifier Rules

  • 1-128 characters long
  • ASCII alphanumeric characters, hyphens, underscores, and dots only
  • Slug format, lowercase recommended (e.g. my-component.tsx, data-pipeline)
  • Must be unique within the chat for creation; reuse the same identifier with x_update_artifact

Versioning

Creating an artifact sets it to version 1. Subsequent updates via x_update_artifact increment the version number. All versions are retained for history.

Use Cases

  • Generating code files with syntax highlighting
  • Creating documentation and technical reports
  • Building interactive HTML previews
  • Rendering architecture diagrams with Mermaid

Example: Code File

JSON
{ "name": "x_create_artifact", "arguments": { "identifier": "fibonacci.py", "title": "Fibonacci Generator", "type": "text/x-python", "language": "python", "content": "def fibonacci(n: int) -> list[int]:\n \"\"\"Generate the first n Fibonacci numbers.\"\"\"\n if n <= 0:\n return []\n if n == 1:\n return [0]\n seq = [0, 1]\n for _ in range(2, n):\n seq.append(seq[-1] + seq[-2])\n return seq\n\nif __name__ == \"__main__\":\n print(fibonacci(10))\n" } }

Example: Mermaid Diagram

JSON
{ "name": "x_create_artifact", "arguments": { "identifier": "auth-flow", "title": "Authentication Flow", "type": "text/x-mermaid", "content": "sequenceDiagram\n participant U as User\n participant A as API Gateway\n participant S as Auth Service\n participant D as Database\n U->>A: POST /login\n A->>S: Validate credentials\n S->>D: Query user\n D-->>S: User record\n S-->>A: JWT token\n A-->>U: 200 OK + token\n" } }

SSE Event

SSE
data: {"type":"x_artifact.created","artifactId":"cart_7f3k2m9q4x1b8n5p0w6d2hvz","identifier":"auth-flow","title":"Authentication Flow","contentType":"text/x-mermaid","version":1}

x_update_artifact

Updates a previously created artifact with new content, creating a new version. The update is a full replacement, the entire content is replaced, not a diff or patch. It is enabled the same way as x_create_artifact.

Parameters

ParameterTypeDescription
identifierrequired string The identifier of the artifact to update. Must match a previously created artifact in this chat.
contentrequired string The complete updated content. Replaces the previous version entirely.

Use Cases

  • Iterating on code based on user feedback
  • Refining documents and reports
  • Updating diagrams with new components
  • Fixing bugs in previously generated code

Example Tool Call

JSON
{ "name": "x_update_artifact", "arguments": { "identifier": "fibonacci.py", "content": "from functools import lru_cache\n\n@lru_cache(maxsize=None)\ndef fibonacci(n: int) -> int:\n \"\"\"Return the nth Fibonacci number (memoized).\"\"\"\n if n < 2:\n return n\n return fibonacci(n - 1) + fibonacci(n - 2)\n\ndef fibonacci_sequence(count: int) -> list[int]:\n \"\"\"Generate the first count Fibonacci numbers.\"\"\"\n return [fibonacci(i) for i in range(count)]\n\nif __name__ == \"__main__\":\n print(fibonacci_sequence(10))\n" } }

SSE Event

SSE
data: {"type":"x_artifact.updated","artifactId":"cart_9b2n6c4d8f1h3j5k7m0p2q4r","identifier":"fibonacci.py","title":"Fibonacci Generator","contentType":"text/x-python","version":2}

x_create_mockup

Creates a multi-file mockup bundle (HTML, CSS, JavaScript, and other static assets) intended for visual preview. Unlike x_create_artifact, which stores a single file, a mockup bundle groups several related files that reference each other through relative paths. The bundle is rendered inside a sandboxed iframe so the model can demonstrate visual designs and interactive prototypes without exposing the host page to the bundle's scripts.

Availability: x_create_mockup is not offered in chat and is not accepted in x_tools. Declared as a function in a Responses request's own tools array, it is removed unless the request is bound to a chat. The model builds bundles with x_add_mockup_file (incremental, one file per call) and x_update_mockup (delete + bulk-replace against an existing bundle) instead, on agentic turns where they are enabled; see Enabling Server-Side Tools.

Parameters

ParameterTypeDescription
identifierrequired string Stable slug for this bundle. 1-128 characters, ASCII alphanumeric, hyphens, underscores, and dots only. Used to reference the bundle for later updates.
titlerequired string Human-readable display title for the mockup.
entryrequired string Relative path within the bundle of the entry document loaded by the preview iframe (e.g. index.html). Must match one of the supplied file paths.
filesrequired array Array of file objects that make up the bundle. See file object schema below. At least one file is required and one of them must match entry.

File Object Schema

FieldTypeDescription
pathrequired string Relative path within the bundle (e.g. index.html, css/main.css, js/app.js). Must not start with / or contain .. segments.
contentoptional string The file's content. Plain text for text files; base64 for binary assets when encoding is base64. Required unless source_artifact_id is given; never sent with it.
source_artifact_idoptional string In place of content: the artifact id (cart_...) of a PNG, JPEG, GIF, or WebP image stored in the workspace, such as an image generated earlier in the chat. The image is copied into the bundle at path in its own format; a path whose extension names another image format is written under the image's own extension. See Placing images.
encodingoptional string Either utf8 (default) or base64. Use base64 for binary assets such as images.

Bundle Preview URL

Each persisted file in a bundle is reachable via:

HTTP
GET /v1/mockups/{bundleId}/{path}

The bundleId is returned in the x_mockup.created event (see the streaming docs). The route is intended for sandboxed-iframe rendering only, responses include a strict Content-Security-Policy and are not meant to be embedded in unsandboxed contexts.

Use Cases

  • Demonstrating a multi-file UI design (HTML + CSS + JS) inside the chat
  • Building interactive prototypes with multiple linked pages
  • Sharing a small static site preview without leaving the chat

Example Tool Call

JSON
{ "name": "x_create_mockup", "arguments": { "identifier": "landing-page", "title": "Landing Page Mockup", "entry": "index.html", "files": [ { "path": "index.html", "content": "<!doctype html>\n<html>\n<head>\n <link rel=\"stylesheet\" href=\"css/main.css\">\n</head>\n<body>\n <h1>Hello</h1>\n <script src=\"js/app.js\"></script>\n</body>\n</html>\n" }, { "path": "css/main.css", "content": "body { font-family: system-ui; margin: 2rem; }\nh1 { color: #C03812; }\n" }, { "path": "js/app.js", "content": "console.log('mockup loaded');\n" } ] } }

SSE Event

SSE
data: {"type":"x_mockup.created","bundleId":"mkp_8f3k2m","identifier":"landing-page","title":"Landing Page Mockup","entry":"index.html","files":[{"path":"index.html","contentType":"text/html","size":182},{"path":"css/main.css","contentType":"text/css","size":74},{"path":"js/app.js","contentType":"application/javascript","size":28}]}

x_add_mockup_file

Writes a single file into a mockup bundle keyed by identifier. The first call for a new identifier creates the bundle (title is required on that call); subsequent calls with the same identifier add or replace files in that bundle. Each call carries one file's worth of content, so the tool-call arguments JSON stays small and survives output-token cuts that routinely truncate create_mockup's atomic "every file in one call" payload.

Availability: x_add_mockup_file is the preferred mockup-authoring path. It is offered only on an agentic turn bound to a chat, and only when it is enabled: in chat through the Mockup group of the workspace's Default tools. For the Responses API rules, see Enabling Server-Side Tools.

Parameters

ParameterTypeDescription
identifierrequired string Stable slug for the bundle. Reuse the same value across calls so files accumulate into one bundle.
titlerequired string Human-readable display title. The first call for an identifier must carry it, and any later call that carries a title replaces the bundle's title, so send the same title on each call.
pathrequired string Relative path within the bundle (e.g. index.html, css/main.css, js/app.js). Must not start with / or contain .. segments.
contentoptional string The file's content. Plain text for text files; base64 for binary assets when encoding is base64. Required unless source_artifact_id is given; never sent with it.
source_artifact_idoptional string In place of content: the artifact id (cart_...) of a PNG, JPEG, GIF, or WebP image stored in the workspace, such as an image generated earlier in the chat. The image is copied into the bundle at path in its own format; a path whose extension names another image format is written under the image's own extension. See Placing images.
encodingoptional string Either utf8 (default) or base64. Use base64 for binary assets such as images.
entryoptional string Entry document loaded by the preview iframe. Defaults to index.html. A later call that carries a title but no entry resets the entry to index.html, so send a custom entry on each call.

Use Cases

  • Any mockup whose files contain HTML, CSS, JavaScript, or other quote-laden content (avoids parser truncation that breaks create_mockup).
  • Multi-file bundles built up over several turns of a conversation.
  • Adding a file to an existing bundle without rewriting the whole bundle.

Example Tool Calls

Two calls sharing the same identifier assemble one bundle. The first call creates the bundle and supplies title; the second call adds another file.

JSON (call 1)
{ "name": "x_add_mockup_file", "arguments": { "identifier": "landing-page", "title": "Landing Page Mockup", "path": "index.html", "content": "<!doctype html>\n<html>\n<head>\n <link rel=\"stylesheet\" href=\"css/main.css\">\n</head>\n<body>\n <h1>Hello</h1>\n</body>\n</html>\n" } }
JSON (call 2)
{ "name": "x_add_mockup_file", "arguments": { "identifier": "landing-page", "path": "css/main.css", "content": "body { font-family: system-ui; margin: 2rem; }\nh1 { color: #C03812; }\n" } }

Placing images

A mockup can show real images instead of empty boxes. When the chat can generate images, the model generates the pictures a design needs (a hero, product shots, a background), choosing each image's shape from where it goes, and places each one with a call that passes the image's artifact id as source_artifact_id in place of content. The image is copied into the bundle in its own format with embedded metadata (EXIF, text chunks) removed. A PNG is sized for the web: scaled down by a whole factor until its longer side is at most 1600 pixels (a 2048x2048 image is placed at 1024x1024) and recompressed. JPEG, GIF, and WebP images are placed at their stored size. The format never changes: a path whose extension names another image format is written at the same name under the image's own extension (a PNG sent as images/hero.jpg is written as images/hero.png), and the result reports the path written. An image placed in a mockup is not repeated after the chat reply. When images cannot be generated, or a generation is refused, the model uses a CSS gradient or a labelled placeholder instead.

The image must belong to the same workspace, and to the same chat or one every member of this chat can read. Any other id, or an artifact that is not an image, is refused with an x_mockup.error whose code is invalid_source, and nothing is written. A successful call's result lists each placed image under placed_images with its path, source_artifact_id, content_type, bytes, width, and height of the file written, so the page can reference it at its real size. An image written under another extension also carries requested_path, the path the call named, and a note naming the path to reference.

JSON (placing an image)
{ "name": "x_add_mockup_file", "arguments": { "identifier": "landing-page", "title": "Landing Page Mockup", "path": "images/hero.png", "source_artifact_id": "cart_aSsRpcGVI9XJIfCqgl4xXSPy" } }

SSE Events

The first call for a new identifier emits x_mockup.created; subsequent calls against the same identifier emit x_mockup.updated with the changed paths. Failures emit x_mockup.error. Payload schemas are documented in the streaming reference.

x_update_mockup

Updates an existing mockup bundle. Files listed in files are added or replaced; paths listed in delete are removed. Files that are not mentioned remain unchanged. Each updated file gets its version incremented. x_update_mockup is offered under the same rules as x_add_mockup_file.

Parameters

ParameterTypeDescription
identifieroptional string The identifier of a previously created bundle in this chat. One of identifier or bundle_id is required.
bundle_idoptional string The opaque bundle id returned in x_mockup.created. One of identifier or bundle_id is required.
titleoptional string New display title. Omit to leave unchanged.
entryoptional string New entry path. Must match an existing or newly added file. Omit to leave unchanged.
filesoptional array Files to add or replace. Same schema as create_mockup, including source_artifact_id in place of content to place an image.
deleteoptional array Array of relative paths to remove from the bundle. The current entry path cannot be deleted unless entry is also reassigned.

Use Cases

  • Iterating on a mockup based on user feedback
  • Adding a new page or asset to an existing bundle
  • Removing files that are no longer part of the design

Example Tool Call

JSON
{ "name": "x_update_mockup", "arguments": { "identifier": "landing-page", "files": [ { "path": "css/main.css", "content": "body { font-family: system-ui; margin: 2rem; background: #0B0D0C; color: #F2EEE6; }\nh1 { color: #E8724F; }\n" } ], "delete": ["js/app.js"] } }

SSE Event

SSE
data: {"type":"x_mockup.updated","bundleId":"mkp_8f3k2m","identifier":"landing-page","title":"Landing Page Mockup","entry":"index.html","changed":["css/main.css"],"deleted":["js/app.js"]}

x_ask_user

Pauses the response and asks the user a clarifying question. The model uses this when ambiguity prevents a useful response. Supports multiple interaction styles: free-text questions, multiple-choice options, confirmation prompts, rating scales, and structured form fields. In chat it is offered when the workspace's Default tools include it, in the Interactive group; on the Responses API, list it in x_tools. See Enabling Server-Side Tools.

Parameters

ParameterTypeDescription
questionrequired string The clarifying question to ask the user.
optionsoptional string[] List of suggested answers for the user to pick from.
allow_free_textoptional boolean Whether the user can type a free-text answer in addition to picking an option. Default: true.
multi_selectoptional boolean Whether the user can select more than one option. Default: false.
styleoptional string Card style. One of: default, confirm, rating, form. Default: default.
fieldsoptional object[] Form fields for form style cards. Each field has label, key, and optional placeholder and required.

Fields Sub-Parameters (for form style)

FieldTypeDescription
labelrequired string Display label for the input field.
keyrequired string Machine-readable key for the field value.
placeholderoptional string Placeholder text shown in the input.
requiredoptional boolean Whether the field must be filled. Default: false.

Card Styles

Default Style

A question with optional multiple-choice options and free-text input.

JSON
{ "name": "x_ask_user", "arguments": { "question": "Which programming language would you like the example in?", "options": ["Python", "JavaScript", "Go", "Rust"], "allow_free_text": true } }

Confirm Style

A Yes/No confirmation prompt.

JSON
{ "name": "x_ask_user", "arguments": { "question": "This will overwrite the existing configuration. Proceed?", "style": "confirm" } }

Rating Style

A 1-5 rating scale.

JSON
{ "name": "x_ask_user", "arguments": { "question": "How satisfied are you with this solution?", "style": "rating" } }

Form Style

Labeled input fields for collecting structured data.

JSON
{ "name": "x_ask_user", "arguments": { "question": "Please provide the database connection details:", "style": "form", "fields": [ {"label": "Host", "key": "host", "placeholder": "localhost", "required": true}, {"label": "Port", "key": "port", "placeholder": "5432", "required": true}, {"label": "Database Name", "key": "db_name", "placeholder": "myapp_production", "required": true}, {"label": "Username", "key": "username", "placeholder": "admin"}, {"label": "Password", "key": "password", "placeholder": "********"} ] } }

Use Cases

  • Disambiguating vague requirements before generating code
  • Collecting structured configuration input
  • Getting user confirmation before destructive operations
  • Offering choices when multiple valid approaches exist

How the Turn Ends

A call to x_ask_user ends the turn. No answer is generated in the user's place: the response carries the call as a function_call output item and completes. A caller with vendor events on also receives the two events below. All field names are camelCase.

SSE
data: {"type":"x_ask_user.question","askUserId":"5f0c1e2a-9d4b-4c8e-a6f1-2b7d3e9c4a10","toolCallId":"call_42","question":"Which programming language?","options":["Python","JavaScript","Go","Rust"],"allowFreeText":true,"multiSelect":false,"style":"default","fields":[]} data: {"type":"x_ask_user.pending_state","assistantContent":"","toolCalls":[{"id":"call_42","type":"function","function":{"name":"x_ask_user","arguments":"{\"question\":\"Which programming language?\",\"options\":[\"Python\",\"JavaScript\",\"Go\",\"Rust\"]}"}}]}

When the turn ran server tools before it asked, the pending state also carries priorToolCalls: each call's id, name, arguments, and output, the most recent eight, each output cut at 4,000 characters and 16,000 in all.

In chat, the question event renders the question card, and the user's answer resumes the turn with the asking turn's tools. The resumed turn sees the tool calls the asking turn already ran and receives the answer once, as the question call's output. An API caller answers the call like any function call: send a function_call_output item with the call's call_id in the next request.

x_propose_schedule

Proposes a scheduled task when the user asks for something to happen regularly or later ("every Monday", "tomorrow at 9"). The call writes nothing. It checks the draft with the same rules as creating a task, prices it, and shows the proposal as a card under the reply: Review and schedule opens the configuration card, where Schedule creates the task, and Dismiss drops it. Nothing is scheduled until the user confirms.

The router offers the tool itself, not through Default tools or x_tools: only on a streamed turn in the web chat or Erebine Desktop Chat, in a workspace that keeps content, where scheduled tasks are on. An API or MCP request, and a scheduled run, never get it; a call from anywhere else answers x_propose_schedule runs only on an Erebine chat turn.

Parameters

ParameterTypeDescription
namerequired string A short label, at most 120 characters.
definitionrequired object kind research with a topic (at most 2,000 characters) and an optional depth, deep (default) or auto; or kind prompt with a prompt (at most 8,000 characters).
schedulerequired object kind (once, interval or cron) and timezone, with at, every, unit, start_at or expression as the kind needs. See Schedules.
toolsoptional string[] MCP tool names the runs may use, such as erebine.research.web_search. Omit for the kind's default set. See Tools.
reasonrequired string One line, in the user's terms, on why this schedule. Kept to 280 characters.

The endpoint answering the turn becomes the task's model, the chat's workspace its workspace, and the estimate's suggested caps its caps. One reply proposes once: a second call answers One schedule proposal per reply. The first one stands. A draft the rules refuse answers the refusal's message, and the model may correct it and call again. A proposal the user has already scheduled or dismissed cannot be decided again.

x_save_memory

Saves a fact, preference, or instruction to the per-workspace memory store. The content is embedded as a vector and persisted to the database for future semantic recall. Near-duplicate content is automatically deduplicated via embedding similarity comparison. It is offered when enabled: in chat through the Workspace memory group of the workspace's Default tools, and on the Responses API through x_tools; see Enabling Server-Side Tools.

Parameters

ParameterTypeDescription
contentrequired string The fact, preference, or instruction to save to memory.
categoryoptional string Category of the memory entry. One of: preference, fact, instruction. When omitted, the system infers the category from the content.

Deduplication

When saving, the system checks for existing memories with very high semantic similarity. If a near-duplicate is found, the save is skipped and the existing memory is returned instead. This prevents the memory store from accumulating redundant entries.

Use Cases

  • Storing user formatting preferences
  • Remembering project details and deadlines
  • Saving coding style instructions
  • Persisting domain-specific knowledge for the conversation

Example Tool Call

JSON
{ "name": "x_save_memory", "arguments": { "content": "User prefers TypeScript with strict mode enabled for all code examples", "category": "preference" } }

Example Response

JSON
{ "status": "saved", "memory_id": "mem_x7k9p2", "content": "User prefers TypeScript with strict mode enabled for all code examples", "category": "preference" }

For full details on memory architecture, passive injection, and the management API, see Chat Memory.

x_recall_memory

Searches the per-workspace memory store using semantic similarity. Returns the top matching memories ranked by relevance score. It is enabled the same way as x_save_memory.

Parameters

ParameterTypeDescription
queryrequired string Natural language query to search memories against.
limitoptional integer Max memories to return.
offsetoptional integer Zero-based row offset for pagination.

Return Value

Returns a ranked markdown list of matching memories.

Use Cases

  • Retrieving user preferences before generating output
  • Looking up previously mentioned facts and context
  • Checking for saved instructions before starting a task

Example Tool Call

JSON
{ "name": "x_recall_memory", "arguments": { "query": "What programming language does the user prefer?" } }

Example Response

JSON
{ "memories": [ { "id": "mem_x7k9p2", "content": "User prefers TypeScript with strict mode enabled for all code examples", "category": "preference", "relevance": 0.94, "created_at": "2026-03-09T14:22:00Z" }, { "id": "mem_r3m8q1", "content": "Always use ESLint with the recommended ruleset", "category": "instruction", "relevance": 0.78, "created_at": "2026-03-09T14:18:00Z" } ] }

For full details on memory architecture, passive injection, and the management API, see Chat Memory.

x_forget

Retracts a memory, decision, milestone, or artifact the model created earlier in the session. The delete is soft: the entity remains visible in the app and the CLI and can be restored there. Use this for model self-correction only. User-requested deletion is done in the app or CLI, not via this tool.

Parameters

ParameterTypeDescription
typerequired string Entity type to retract. One of: memory, decision, milestone, artifact.
idrequired string The handle the original tool returned: the mem_ id for memory, the dec_ id for decision, the mst_ id for milestone (each also accepts the entity's row UUID), or the identifier slug or cart_ id for artifact. An artifact is retracted in the current chat only (outside a chat, the workspace's own): another chat's artifact with the same identifier is not touched.

Example Tool Call

JSON
{ "name": "x_forget", "arguments": { "type": "decision", "id": "dec_a1b2c3d4e5f6g7h8" } }

Agentic Loop

When server-side tools are enabled, Erebine uses an agentic loop to iteratively call tools and feed results back to the model. This loop is the foundational mechanism that powers all server-side tool execution, including research workflows and the research pipeline.

How the Loop Works

  1. Model response, The model generates a response that may include one or more tool calls.
  2. Tool execution, Erebine executes the requested tools server-side (e.g., x_web_search, x_fetch_url, x_code_search).
  3. Result injection, Tool results are appended to the conversation as tool-role messages.
  4. Follow-up, The model generates another response based on the tool results. This response may include additional tool calls.
  5. Termination, Steps 2-4 repeat until the model produces a final text response (no tool calls) or the iteration limit is reached.

Limits

LimitValueDescription
Maximum iterations per request 5 The loop runs at most 5 tool-call rounds before forcing a final response. This is the nominal default; on the augmented chat surface the loop may extend slightly, by one round per repaired malformed step up to a small ceiling, to recover from a defective step.
Per-tool execution timeout 15 seconds Each individual tool call must complete within 15 seconds or it is cancelled.
Tool call rate limit 45 / minute Maximum of 45 tool calls per minute per endpoint to prevent abuse.

Automatic Behavior

The agentic loop runs automatically whenever tools such as x_web_search, x_fetch_url, x_code_search, or x_calculator are enabled via a web_search tool entry on the Responses API. No additional client-side configuration is required, the router handles all tool execution, result marshalling, and follow-up model calls transparently.

If the model does not invoke any tools, the loop completes in a single iteration and the response is returned directly. When the maximum iteration limit is reached, the model is prompted to produce a final answer using the information gathered so far.

In chat, the loop is visible while it runs. Each round adds its thinking and its narration to the activity panel above the answer, and both grow as the loop iterates. When the answer starts streaming, the narration is retired and the thinking trail stays, dimmed, for the rest of the turn. Direct API callers are unaffected: the answer and its payload do not change.

Note: Research depth extends this agentic loop with a multi-phase planning and synthesis layer on top. Each research sub-task runs its own agentic loop independently.

Research Depth

Vendor extension. The research_depth field is an Erebine addition, not part of the OpenAI request schema. Standard OpenAI-compatible clients omit it and get a plain agentic turn.

research_depth is a top-level request field on /v1/chat/completions and the Responses API. It sets how much research the turn does, on a three-position dial:

ValueBehavior
off No research stages run. The turn is a plain agentic loop.
auto default Research runs within the turn, at conservative budgets, when the question warrants it; otherwise the turn is a plain agentic loop (see Research on auto turns).
deep The full research pipeline: source discovery, sub-task fan-out, cross-referencing, deepening rounds, and synthesis. This is deep research in the chat interface.

A research scheduled task runs its topic at deep or auto on a schedule, unattended.

How depth is resolved

The effective depth for a turn is resolved in this order:

  1. A turn that does not opt into vendor events is always off. Research never runs on a plain OpenAI-compatible request.
  2. An explicit research_depth field on the request wins. An unrecognized value is ignored, and the next rule applies.
  3. Otherwise the workspace research_depth preference applies.
  4. With no field and no preference, the default is auto.

The per-turn field always overrides the workspace preference, so a client can force off or deep for a single turn without changing the workspace default.

In chat, a turn sent with Agentic Workflows off does not take a workspace preference of deep: it runs at off unless the turn names its own depth.

Setting research depth

Set research_depth at the top level of the request body.

JSON
{ "model": "my-model", "messages": [ {"role": "user", "content": "Comprehensive analysis of quantum computing advances in 2026"} ], "stream": true, "research_depth": "deep" }

Research on auto turns

On an auto turn the router decides, before answering, whether the question needs research. When it does, the turn runs the research pipeline itself, at auto budgets: fewer sub-tasks and one deepening round. When it does not, the turn is a plain agentic loop. No follow-up run is proposed after a turn has answered; the x_research.escalation_* events below are reserved and not emitted.

A research run started by a chat turn belongs to the router, not to the connection. A client that detaches sees x_research.run_detached; the run continues and delivers its result into the chat. A run interrupted by a router restart resumes from its last checkpoint, except in a workspace that keeps no content, where it ends as failed.

Stream sequence

On a streaming deep turn the SSE stream interleaves research-pipeline events (see Research Pipeline Events) with the synthesized answer, which arrives as normal content chunks.

Sequence
1. x_research.plan_created , plan ready, includes the sub-task count 2. x_research.subtask_started , sub-task N begins (repeated per sub-task) x_research.searching / x_research.reading , tool-level events within sub-task 3. x_research.subtask_completed , sub-task N finished ... (repeat 2-3 for each sub-task) ... 4. x_research.synthesis_started , synthesis phase begins data: {"choices":[...]} , normal SSE content chunks (final answer) 5. x_research.synthesis_completed, synthesis finished 6. x_research.round_completed , a deepening round finished (repeated per round) x_research.answer_update.started , the round checks whether its evidence changes the answer x_research.answer_update.completed , updated (with the whole revised answer), unchanged or failed 7. x_research.run_completed , pipeline finished 8. data: [DONE] , stream terminates

Updated answers

The answer streams once, from the first synthesis, so the first text arrives as early as it can. Each deepening round that follows gathers more evidence and then checks whether that evidence changes the answer: it corrects a statement, settles a question the answer left open, or changes a conclusion, a figure or a recommendation. When it does, the round sends x_research.answer_update.completed with outcome updated, a one-sentence change, and the whole revised answer as body. Better wording or more of the same is not a change; such a round reports unchanged.

The streamed content is never rewritten: the content chunks and the final message carry the first answer, as an OpenAI-compatible stream must. A client that renders research events replaces the answer it shows with each update's body; the last update is the answer of record. revision numbers them: 1 is the first answer, and x_research.run_completed carries the revision the run ended on. On the Responses API, the stored response (GET /v1/responses/{id} and a later turn's previous_response_id) holds the answer of record.

No update is made when the request does not opt into vendor events (a plain OpenAI client gets one answer, the one it streamed), when it sets a response_format other than text, or when it bounds the output with max_tokens, max_completion_tokens or max_output_tokens. A round whose update fails leaves the answer as it was.

In the web chat, the desktop app and the iOS app an updated answer is replaced in place and marked UPDATED with the round and what changed; Earlier versions lists every version. The reader's place in the conversation is kept, and copy and read aloud use the answer of record.

Revising an answer

Vendor extension. The research_revision field is an Erebine addition to the Responses API, not part of the OpenAI request schema.

A finished deep research answer can be revised on request. The request is a Responses API turn that carries research_revision; its last user message says what should change. The turn carries the answer's research forward, runs a short research round on the request, and checks whether the answer should change, as a deepening round does. A revision becomes the answer's next revision: there is still one answer.

FieldDescription
message_id Identifies the answer. When the chat holds research for that message, the research is carried forward; otherwise the round gathers new evidence only.
revision optional The answer's current revision. Defaults to 1.
answer The answer as the reader has it, which the revision starts from.

A revision runs at deep. A request that names another research_depth, declares no web search tool, or declares an image_generation tool is rejected with 400 invalid_request_error.

The response is one message: the revised answer, or the reason the answer stands, or "The answer could not be revised; it stands as revision N." The research events are the ones above, with origin request: x_research.answer_update.completed carries the new revision, change and body when the answer changed, and the standing revision, with reason when the model gave one, when it did not.

In the web chat, the desktop app and the iOS app, Revise on a research answer puts the composer in a revising mode, Revising: <title>. Send what should change, or send it empty to research the answer further. The answer shows REVISING with the run's progress, then UPDATED with your request and what changed, or NOT REVISED with the reason. Earlier versions lists each revision and the request that made it. A workspace that keeps no content cannot revise answers.

Research Pipeline Events (SSE)

Research-pipeline progress events are emitted as inline SSE data lines with a type field prefixed by x_research.. Clients should check for this prefix and render progress UI accordingly. These describe the pipeline lifecycle (plan, sub-tasks, synthesis, deepening, escalation, run state); the per-tool x_research.searching / reading / etc. events are listed separately under SSE Events Reference.

Every pipeline event carries a common envelope: run_id (the research run the event belongs to), depth (off / auto / deep), stage (e.g. plan, subtasks, synthesis), round (the 1-based deepening round), and, where applicable, subtask_index and attempt.

Event TypeDescription
x_research.escalation_proposed Reserved; not emitted.
x_research.escalation_started Reserved; not emitted.
x_research.escalation_cancelled Reserved; not emitted.
x_research.plan_created The planner produced the initial research plan. Carries title when the planner wrote one.
x_research.plan_updated The plan changed (critique pass or per-round follow-ups).
x_research.subtask_started A research sub-task began executing.
x_research.subtask_delta Output-token delta from a sub-task.
x_research.subtask_reasoning_delta Reasoning-token delta from a sub-task (coalesced server-side).
x_research.subtask_completed A research sub-task finished.
x_research.subtask_retried A weak sub-task result triggered a retry attempt.
x_research.synthesis_started Final synthesis began streaming. Content chunks follow as normal SSE.
x_research.synthesis_delta Synthesis output-token delta.
x_research.synthesis_completed Final synthesis finished.
x_research.claim A structured claim extracted during synthesis.
x_research.cross_reference A cross-reference between sub-task findings.
x_research.gaps Gap-analysis result for a deepening round.
x_research.round_completed A deepening round finished.
x_research.converged Gap analysis found nothing actionable; deepening stops early.
x_research.heartbeat Cadence emission during a long stage wait.
x_research.intelligence_persisted The intelligence bundle (memories, artifacts, project-intelligence) was persisted.
x_research.answer_update.started A deepening round is checking whether its evidence changes the answer. Carries revision, the number an update would take.
x_research.answer_update.completed The round's check finished: outcome is updated, unchanged or failed, with revision; an update also carries change (one sentence) and body (the whole revised answer). A revision request's frames carry origin request, and reason when the answer stands. See Updated answers and Revising an answer.
x_research.run_detached The live run detached from the turn and continues in the background.
x_research.run_completed Terminal: the run completed successfully. Carries title, the run's title: the planner's title, else the report's first heading, else the question, and revision, the answer's revision the run ended on.
x_research.run_failed Terminal: the run failed.
x_research.error A non-terminal pipeline error surfaced to the consumer.

Example Event Stream

SSE
data: {"type":"x_research.plan_created","run_id":"a1b2c3d4-0000-4000-8000-000000000000","depth":"deep","stage":"plan","round":1} data: {"type":"x_research.subtask_started","run_id":"a1b2c3d4-0000-4000-8000-000000000000","depth":"deep","stage":"subtasks","round":1,"subtask_index":0} data: {"type":"x_research.searching","name":"x_web_search","arguments":"{\"query\":\"quantum error correction 2026\"}"} data: {"type":"x_research.subtask_completed","run_id":"a1b2c3d4-0000-4000-8000-000000000000","depth":"deep","stage":"subtasks","round":1,"subtask_index":0} ... data: {"type":"x_research.synthesis_started","run_id":"a1b2c3d4-0000-4000-8000-000000000000","depth":"deep","stage":"synthesis","round":1} data: {"choices":[{"index":0,"delta":{"content":"# Quantum Computing Advances\n\n"},"finish_reason":null}]} ... data: {"type":"x_research.synthesis_completed","run_id":"a1b2c3d4-0000-4000-8000-000000000000","depth":"deep","stage":"synthesis","round":1} data: {"type":"x_research.run_completed","run_id":"a1b2c3d4-0000-4000-8000-000000000000","depth":"deep","stage":"synthesis","round":1,"title":"Quantum Computing Advances"} data: [DONE]

SSE Events Reference

When streaming, server-side tool execution emits inline SSE events so clients can display progress indicators. All vendor-specific events use the x_ prefix for OpenAI spec compliance.

Research Events

Event TypeToolDescription
x_research.searching x_web_search Emitted when a web search begins execution.
x_research.reading x_fetch_url Emitted when a URL fetch begins execution.
x_research.code_searching x_code_search Emitted when a code search begins execution.
x_research.calculating x_calculator Emitted when a calculator evaluation begins.
x_research.tool_call Any Emitted for tool invocations that do not match a specific research event type. Includes tool_name, message.
x_research.result All research tools Emitted when a tool call completes with its result.
x_research.complete -- Declared in the event vocabulary and consumed by the chat dashboard, but not currently emitted by any router-side code path on the public /v1/chat/completions stream. Documented for future parity; do not depend on it from public-API clients yet.

Artifact Events

Event TypeDescription
x_artifact.created Emitted when a new artifact is stored. Includes artifactId, identifier, title, contentType, and version. When the router saves a turn's own answer as an artifact, the event also carries origin set to auto, and chat lists the artifact in the artifacts panel without a card in the conversation. An artifact the model writes with x_create_artifact, and a research report the answer summarizes, carry no origin.
x_artifact.updated Emitted when a new version of an existing artifact is stored. Same fields as x_artifact.created.

Ask User Events

Event TypeDescription
x_ask_user.question Emitted when the model asks a clarifying question. CamelCase fields: askUserId, toolCallId, question, options, allowFreeText, multiSelect, style, fields.
x_ask_user.pending_state Emitted with the asking turn's state while awaiting the user's answer. Fields: assistantContent (the turn's prose), toolCalls (the calls the turn ended on), and, when the turn ran server tools first, priorToolCalls (those calls with their outputs).

Research Pipeline Events

The research pipeline (a deep turn, or an escalated auto turn) emits its own x_research.* lifecycle events with a common envelope. They are listed in full under Research Pipeline Events.

File Search Events (Responses API)

Note: the OpenAI-compatible response.file_search_call.* event types below are declared in the router's event vocabulary but are not currently emitted by any router-side code path on the public /v1/chat/completions stream. They are reserved for future parity with the Responses API and should not be relied upon by client integrations yet.

Event TypeDescription
response.file_search_call.in_progress Emitted when a server-side file search invocation begins. Includes item_id, output_index.
response.file_search_call.searching Emitted while the file search is actively executing.
response.file_search_call.completed Emitted when the file search finishes. Includes the completed output item with results.

Chat Metadata Events

Event TypeDescription
x_chat.metadata Emitted at the end of a response stream with aggregated usage metadata including research token counts. Includes usage (object with research token breakdown).

Example SSE Stream

SSE
data: {"type":"x_research.searching","name":"x_web_search","arguments":"{\"query\":\"rust async patterns 2026\"}"} data: {"type":"x_research.result","name":"x_web_search","tool_call_id":"call_1"} data: {"type":"x_research.reading","name":"x_fetch_url","arguments":"{\"url\":\"https://blog.rust-lang.org/...\"}"} data: {"type":"x_research.result","name":"x_fetch_url","tool_call_id":"call_2"} data: {"type":"x_research.calculating","name":"x_calculator","arguments":"{\"expression\":\"2^32\"}"} data: {"type":"x_research.result","name":"x_calculator","tool_call_id":"call_3"} data: {"type":"x_research.complete","elapsed_ms":4200,"input_tokens":12500,"output_tokens":850,"iterations":3,"sources":5} data: {"choices":[{"index":0,"delta":{"content":"Based on my research..."},"finish_reason":null}]} ... data: [DONE]

Rate Limiting & Caching

Per-Project Rate Limiting

Tool calls are rate limited per project (default 45 calls per minute). When the limit is exceeded, the tool returns an error response instead of executing.

Rate Limit Error Response

JSON
{ "error": "Research tool rate limit exceeded. Try again in 12 seconds." }

Result Caching

Identical tool calls (same function name and arguments) within a 30-minute window return cached results without re-executing. This prevents redundant network calls when the model re-invokes the same search or fetch. Auto-fetched URLs from x_web_search are also cached, so subsequent explicit x_fetch_url calls for the same URL are free. x_get_time and x_get_weather are never answered from this cache: a clock reading is never replayed, and weather follows its sources' own caching.

Tool Limits

LimitValueDescription
Rate limit 45/min Maximum tool calls per minute per project.
Cache TTL 30 minutes How long identical tool results are cached.
Auto-fetch count 2 Number of top URLs auto-fetched from web_search results.
Max URLs per fetch 5 Maximum URLs per fetch_url call.
Max follow links 3 Maximum same-domain links to auto-follow in discovery mode.
Character budget 24,000 Character budget for multi-URL fetch results, distributed across pages.

Full API Examples

Research Tools (Responses API)

curl
curl -X POST https://api.erebine.ai/proj_ABC123/my-endpoint/v1/responses \ -H "Authorization: Bearer ere_myproject_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "model": "my-model", "input": "What are the key differences between Rust and Go for building web servers?", "stream": true, "tools": [ { "type": "web_search", "search_context_size": "medium", "x_tools": ["x_web_search", "x_fetch_url", "x_code_search"] } ] }'

All Tools Enabled (Responses API)

curl
curl -X POST https://api.erebine.ai/proj_ABC123/my-endpoint/v1/responses \ -H "Authorization: Bearer ere_myproject_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "model": "my-model", "input": "Compare the async runtimes in Rust and explain the tradeoffs", "stream": true, "tools": [ { "type": "web_search", "search_context_size": "high", "max_iterations": 8, "x_tools": [ "x_web_search", "x_fetch_url", "x_code_search", "x_repo_overview", "x_calculator" ] } ] }'
Python (OpenAI SDK)
from openai import OpenAI client = OpenAI( base_url="https://api.erebine.ai/proj_ABC123/my-endpoint/v1", api_key="ere_myproject_your_api_key", ) response = client.responses.create( model="my-model", input="Compare the async runtimes in Rust and explain the tradeoffs", stream=True, tools=[ { "type": "web_search", "search_context_size": "high", "max_iterations": 8, "x_tools": [ "x_web_search", "x_fetch_url", "x_code_search", "x_repo_overview", "x_calculator" ], } ], ) for event in response: if hasattr(event, "type"): print(event)
Node.js (OpenAI SDK)
import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.erebine.ai/proj_ABC123/my-endpoint/v1", apiKey: "ere_myproject_your_api_key", }); const stream = await client.responses.create({ model: "my-model", input: "Compare the async runtimes in Rust and explain the tradeoffs", stream: true, tools: [ { type: "web_search", search_context_size: "high", max_iterations: 8, x_tools: [ "x_web_search", "x_fetch_url", "x_code_search", "x_repo_overview", "x_calculator" ], } ], }); for await (const event of stream) { console.log(event); }

Responses API with Web Search and a Function Tool

The router runs the web search; the model asks your application for the design spec through the get_design_spec function, which comes back as a function_call output item. Send its result with previous_response_id as a function_call_output item. A file_search tool is not available here and returns 400.

curl
curl -X POST https://api.erebine.ai/proj_ABC123/my-endpoint/v1/responses \ -H "Authorization: Bearer ere_myproject_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "model": "my-model", "input": "Compare our design spec with current best practices for REST API design", "stream": true, "tools": [ { "type": "web_search", "search_context_size": "medium", "x_tools": ["x_web_search", "x_fetch_url"] }, { "type": "function", "name": "get_design_spec", "description": "Return the text of our REST API design spec.", "parameters": {"type": "object", "properties": {}, "additionalProperties": false} } ] }'
Python (OpenAI SDK)
from openai import OpenAI client = OpenAI( base_url="https://api.erebine.ai/proj_ABC123/my-endpoint/v1", api_key="ere_myproject_your_api_key", ) response = client.responses.create( model="my-model", input="Compare our design spec with current best practices for REST API design", stream=True, tools=[ { "type": "web_search", "search_context_size": "medium", "x_tools": ["x_web_search", "x_fetch_url"], }, { "type": "function", "name": "get_design_spec", "description": "Return the text of our REST API design spec.", "parameters": {"type": "object", "properties": {}, "additionalProperties": False}, }, ], ) for event in response: if hasattr(event, "type"): print(event)
Node.js (OpenAI SDK)
import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.erebine.ai/proj_ABC123/my-endpoint/v1", apiKey: "ere_myproject_your_api_key", }); const stream = await client.responses.create({ model: "my-model", input: "Compare our design spec with current best practices for REST API design", stream: true, tools: [ { type: "web_search", search_context_size: "medium", x_tools: ["x_web_search", "x_fetch_url"], }, { type: "function", name: "get_design_spec", description: "Return the text of our REST API design spec.", parameters: { type: "object", properties: {}, additionalProperties: false }, }, ], }); for await (const event of stream) { console.log(event); }

Multi-Tool Conversation Flow (Responses API)

This example shows a typical multi-tool chain where the model searches for information, fetches a page for detail, and uses the calculator to verify a number, all within a single agentic loop. Research progress (x_research.*) events flow inline alongside the answer text.

curl
curl -X POST https://api.erebine.ai/proj_ABC123/my-endpoint/v1/responses \ -H "Authorization: Bearer ere_myproject_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "model": "my-model", "input": "What is the current price of gold per ounce, and how much would 3.5 troy ounces cost in EUR at today'\''s exchange rate?", "stream": true, "tools": [ { "type": "web_search", "search_context_size": "medium", "max_iterations": 6, "x_tools": ["x_web_search", "x_fetch_url", "x_calculator"] } ] }'
Python (OpenAI SDK)
from openai import OpenAI client = OpenAI( base_url="https://api.erebine.ai/proj_ABC123/my-endpoint/v1", api_key="ere_myproject_your_api_key", ) # The model may chain: web_search -> fetch_url -> calculator, # all server-side in a single request. response = client.responses.create( model="my-model", input="What is the current price of gold per ounce, " "and how much would 3.5 troy ounces cost in EUR " "at today's exchange rate?", stream=True, tools=[ { "type": "web_search", "search_context_size": "medium", "max_iterations": 6, "x_tools": ["x_web_search", "x_fetch_url", "x_calculator"], } ], ) for event in response: if event.type == "response.output_text.delta": print(event.delta, end="", flush=True) print()
Node.js (OpenAI SDK)
import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.erebine.ai/proj_ABC123/my-endpoint/v1", apiKey: "ere_myproject_your_api_key", }); // The model may chain: web_search -> fetch_url -> calculator, // all server-side in a single request. const stream = await client.responses.create({ model: "my-model", input: "What is the current price of gold per ounce, " + "and how much would 3.5 troy ounces cost in EUR " + "at today's exchange rate?", stream: true, tools: [ { type: "web_search", search_context_size: "medium", max_iterations: 6, x_tools: ["x_web_search", "x_fetch_url", "x_calculator"], } ], }); for await (const event of stream) { if (event.type === "response.output_text.delta") { process.stdout.write(event.delta); } } console.log();

Research Depth (curl)

curl
curl -X POST https://api.erebine.ai/proj_ABC123/my-endpoint/v1/chat/completions \ -H "Authorization: Bearer ere_myproject_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "model": "my-model", "messages": [ {"role": "user", "content": "Comprehensive analysis of quantum computing advances in 2026"} ], "stream": true, "research_depth": "deep" }'

Research Depth (Python)

Python (OpenAI SDK)
import json from openai import OpenAI client = OpenAI( base_url="https://api.erebine.ai/proj_ABC123/my-endpoint/v1", api_key="ere_myproject_your_api_key", ) stream = client.chat.completions.create( model="my-model", messages=[ {"role": "user", "content": "Comprehensive analysis of quantum computing advances in 2026"} ], stream=True, extra_body={"research_depth": "deep"}, ) for chunk in stream: raw = chunk.model_dump() # Check for research pipeline progress events if "type" in raw and raw["type"].startswith("x_research."): print(f"[{raw['type']}]", json.dumps(raw, indent=2)) continue # Normal content chunks if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="") print()
Node.js (OpenAI SDK)
import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.erebine.ai/proj_ABC123/my-endpoint/v1", apiKey: "ere_myproject_your_api_key", }); const stream = await client.chat.completions.create({ model: "my-model", messages: [ { role: "user", content: "Comprehensive analysis of quantum computing advances in 2026" } ], stream: true, research_depth: "deep", }); for await (const chunk of stream) { const raw = chunk; // Check for research pipeline progress events if (raw.type && raw.type.startsWith("x_research.")) { console.log(`[${raw.type}]`, JSON.stringify(raw, null, 2)); continue; } // Normal content chunks const content = chunk.choices?.[0]?.delta?.content; if (content) process.stdout.write(content); } console.log();

A deep turn streams and emits progress events inline. The synthesized answer is streamed as normal content chunks after the sub-tasks complete, and is also saved as an artifact in the chat interface.

Artifact Creation Flow

List the artifact tools in x_tools and send X-Erebine-Vendor-Events: 1 to receive the x_artifact.created and x_artifact.updated events. Each names the stored artifact by artifactId.

curl
curl -N -X POST https://api.erebine.ai/proj_ABC123/my-endpoint/v1/responses \ -H "Authorization: Bearer ere_myproject_your_api_key" \ -H "Content-Type: application/json" \ -H "X-Erebine-Vendor-Events: 1" \ -d '{ "model": "my-model", "input": "Create a Python script that implements a binary search tree with insert, search, and in-order traversal methods.", "stream": true, "tools": [ { "type": "web_search", "x_tools": ["x_create_artifact", "x_update_artifact"] } ] }'
Python (httpx)
import json import httpx url = "https://api.erebine.ai/proj_ABC123/my-endpoint/v1/responses" headers = { "Authorization": "Bearer ere_myproject_your_api_key", "X-Erebine-Vendor-Events": "1", } body = { "model": "my-model", "input": "Create a Python script that implements a binary search tree " "with insert, search, and in-order traversal methods.", "stream": True, "tools": [ {"type": "web_search", "x_tools": ["x_create_artifact", "x_update_artifact"]} ], } with httpx.stream("POST", url, headers=headers, json=body, timeout=None) as response: for line in response.iter_lines(): if not line.startswith("data: {"): continue event = json.loads(line[len("data: "):]) if event.get("type") in ("x_artifact.created", "x_artifact.updated"): print(f"\n[{event['type']}] {event['identifier']} " f"- {event['title']} (v{event['version']}, {event['artifactId']})") elif event.get("type") == "response.output_text.delta": print(event["delta"], end="") print()
Node.js (fetch)
const response = await fetch( "https://api.erebine.ai/proj_ABC123/my-endpoint/v1/responses", { method: "POST", headers: { "Authorization": "Bearer ere_myproject_your_api_key", "Content-Type": "application/json", "X-Erebine-Vendor-Events": "1", }, body: JSON.stringify({ model: "my-model", input: "Create a Python script that implements a binary search tree " + "with insert, search, and in-order traversal methods.", stream: true, tools: [ { type: "web_search", x_tools: ["x_create_artifact", "x_update_artifact"] }, ], }), }, ); const decoder = new TextDecoder(); let buffered = ""; for await (const chunk of response.body) { buffered += decoder.decode(chunk, { stream: true }); const lines = buffered.split("\n"); buffered = lines.pop(); for (const line of lines) { if (!line.startsWith("data: {")) continue; const event = JSON.parse(line.slice("data: ".length)); if (event.type === "x_artifact.created" || event.type === "x_artifact.updated") { console.log(`\n[${event.type}] ${event.identifier} - ${event.title} ` + `(v${event.version}, ${event.artifactId})`); } else if (event.type === "response.output_text.delta") { process.stdout.write(event.delta); } } } console.log();