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
| Tool | Category | Description |
|---|---|---|
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_link_milestones |
Project Intelligence | Add or remove one link between two items of a plan, or between a plan item and a decision (runs_after, blocked_by, informs, decision); a link that would close a loop is refused |
x_suggest_links |
Project Intelligence | Propose links between the cards of a plan, and from cards to decisions, each with a score and a reason, by any of four methods (embedding, ranking, system1, llm); nothing is saved, and a pair already linked or a link that would close a loop is never suggested; system1 link suggestions are reported as not yet calibrated |
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, andx_image_search.x_web_searchbringsx_fetch_urlwith it, andx_image_searchbringsx_fetch_image. - Code:
x_code_search,x_repo_overview, andx_repo_read. - Math:
x_calculator. - Time and weather:
x_get_timeandx_get_weather. Both are on by default. - Workspace memory:
x_save_memory,x_recall_memory, andx_workspace_search. - Workspace lookup:
x_list_workspacesandx_get_workspace. Both are read-only.x_list_workspaceslists the workspaces the caller can see, held to the API key's workspace allowlist when it has one;x_get_workspacereads 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, andx_analyze_workspace. - Artifacts:
x_create_artifact,x_update_artifact,x_read_artifact, andx_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 switchesx_generate_imagefor the workspace on every surface: chat, the Responses API and MCP. It does not govern the Responses API's hostedimage_generationtool or the Images API. See x_generate_image. - Mockup:
x_add_mockup_fileandx_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.
{
"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.
| Behavior | Details |
|---|---|
| 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.
| Command | Runs | Takes |
|---|---|---|
/brief | x_project_brief | An optional focus |
/decisions | x_query_decisions | An optional query |
/timeline | x_query_timeline | An optional query |
/graph | x_query_graph | Nothing |
/decide | x_track_decision | A title; the form asks for the outcome and why |
/milestone | x_track_milestone | A title; the form asks what happened and its kind |
/relate | x_relate | An id; the form asks for the relationship and the other id |
/recall | x_recall_memory | A query |
/search | x_workspace_search | A query |
/remember | x_save_memory | The fact to save |
/artifacts | x_list_artifacts | Nothing |
/artifact | x_read_artifact | An artifact id |
/code | x_code_search | A query |
/repo | x_repo_overview | owner/name |
/web | x_web_search | A query |
/fetch | x_fetch_url | A URL |
/inspect | x_inspect_site | A URL |
/images | x_image_search | A query |
/calc | x_calculator | An expression |
/time | x_get_time | An optional place; without one, the time in UTC |
/weather | x_get_weather | A 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:
| File | Holds |
|---|---|
index.md | Headed 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.md | The full report, for a deep research turn |
revisions/NN.md | Every 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>.md | One 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.json | Every search: the tool, the query, when it ran, its sub-task, and each result's title, URL and snippet |
images.json | Every image result: its page, title, size, licence and credit |
plan.json | The question, how the research ran, its timings and each pass's sub-tasks |
claims.json | Claims with their sources and confidence, conflicts and open questions, and the answer's citations |
usage.json | Tokens per step and in total |
manifest.json | The 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.
- 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.
- 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.
- Optional LLM polish. When the
workspace's
humanize_polish_enabledis 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. - Post-polish re-scrub. Runs the same rule engine again. Polish models occasionally reintroduce tells; the scrubber is the floor.
- 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).
- 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_web_search
Searches the web using built-in web search. Returns structured
results with titles, URLs, and snippets. The top 2 result URLs
are automatically fetched in parallel and appended as
fetched_pages for immediate full-page context
enrichment in a single tool call.
Web search is a research tool and must be explicitly opted into
via a web_search tool entry on the Responses API
(server tools do not run on Chat Completions).
Including x_web_search in x_tools
automatically enables x_fetch_url as well. See
Enabling Server-Side Tools for request
setup, SSE Events Reference for
streaming progress events, and
Rate Limiting & Caching for
limits.
web_search Tool Parameters
When the model decides to invoke web search, it generates a tool call with the following argument:
| Parameter | Type | Description |
|---|---|---|
| queryrequired | string | The search query to look up on the web. The model formulates this from the user message context. |
Example Tool Call (generated by model)
{
"name": "x_web_search",
"arguments": {
"query": "rust async trait stabilization 2026"
}
}
web_search_options Fields
The fields below are accepted on the
web_search tool object on the Responses API. On
/v1/chat/completions the same fields carried in
web_search_options return 400
unsupported_parameter -- server tools run on Responses.
| Field | Type | Default | Description |
|---|---|---|---|
| search_context_sizeoptional | string | "medium" |
One of: low, medium, high. Sets how many results each x_web_search call returns when the model does not ask for a number: 3, 5 or 8. |
| max_iterationsoptional | integer | 5 |
Maximum agentic loop iterations. Range 1-10. |
| x_toolsoptional | string[] | ["x_web_search", "x_fetch_url"] |
Which research tools to enable. When omitted or empty, defaults to ["x_web_search", "x_fetch_url"]. Including x_web_search auto-includes x_fetch_url. |
| x_analystoptional | boolean | false |
Enables the Analyst sub-agent that post-processes research into a structured analysis. |
| x_execoptional | boolean | false |
Permits the model to invoke server-side execution tools (sandboxed). Subject to project policy. |
| x_exec_approval_policyoptional | string | "never" |
Approval policy for exec tool calls. One of: never, on_request, always. |
Note: multi-phase research is no longer a
web_search_options flag. Set it with the top-level
research_depth field. See Research
Depth.
Response Format
The tool returns a JSON object with the following fields. The router injects this as a tool-role message back to the model.
| Field | Type | Description |
|---|---|---|
answer |
string | Direct answer from the search engine, if available. May be empty. |
abstract |
string | Summary text from the search engine, if available. May be empty. |
results |
object[] | Array of search result objects, each with title, url, and snippet. |
fetched_pages |
object[] | Array of auto-fetched page content for the top 2 URLs. Each entry has url and content. |
Example Response
{
"answer": "",
"abstract": "",
"results": [
{
"title": "Async Trait Methods Stabilized in Rust 1.85",
"url": "https://blog.rust-lang.org/2026/02/20/async-traits.html",
"snippet": "Rust 1.85 stabilizes async fn in traits, enabling..."
},
{
"title": "Understanding async traits in Rust",
"url": "https://docs.rs/async-trait/latest/guide",
"snippet": "A comprehensive guide to using async trait methods..."
}
],
"fetched_pages": [
{
"url": "https://blog.rust-lang.org/2026/02/20/async-traits.html",
"content": "Announcing Rust 1.85. We are happy to announce that async fn in traits..."
},
{
"url": "https://docs.rs/async-trait/latest/guide",
"content": "Async Trait Guide. This guide covers the fundamentals of async trait..."
}
]
}
Auto-Fetch Enrichment
After returning search results, the router automatically fetches
the top 2 result URLs in parallel and appends the extracted text
as fetched_pages. This gives the model both the
search snippets and full page content in a single tool call,
reducing the number of loop iterations needed.
Each auto-fetched page shares an equal portion of a fixed character budget (currently 12,000 characters across all auto-fetched pages, subject to change). Pages exceeding their share are truncated.
Auto-fetched URLs are also cached. If the model subsequently calls
x_fetch_url for a URL that was already auto-fetched, the
cached result is returned instantly without a network request.
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
| Parameter | Type | Description |
|---|---|---|
| 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
urlwithout discovery flags. Returns extracted plain text directly. -
Multi-URL, provide
urlsarray for parallel fetching. Returns a JSON object with apagesarray, each containingurl,content, anderrorfields. -
Discovery, set
discover_links: trueto 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
{
"name": "x_fetch_url",
"arguments": {
"url": "https://docs.example.com/api/authentication"
}
}
Example: Multi-Fetch with Discovery
{
"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
{
"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
data: {"type":"x_research.reading","name":"x_fetch_url","arguments":"{\"url\":\"https://docs.example.com/api/authentication\"}"}
x_code_search
Searches public code on GitHub via the GitHub Code Search API. Returns
code snippets with repository, path, URL, and full file content for the
top results. To inspect an entire repository (metadata, README, tree)
or read specific files from a repo, use x_repo_overview or
x_repo_read instead.
Parameters
| Parameter | Type | Description |
|---|---|---|
| queryrequired | string | GitHub code search query. Supports qualifiers: repo:owner/name, org:name, path:dir/, filename:name, extension:ext, language:lang. |
| limitoptional | integer | Max results to return (defaults to 5, capped at 20). Full file content is fetched only for the top 3. |
| offsetoptional | integer | Zero-based row offset for pagination. Rounded down to the nearest limit boundary because GitHub paginates in fixed-size pages. |
Example
{
"name": "x_code_search",
"arguments": {
"query": "async stream handler repo:apple/swift-nio language:swift",
"limit": 5
}
}
SSE Event
data: {"type":"x_research.code_searching","name":"x_code_search","arguments":"{\"query\":\"async stream handler language:swift\"}"}
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
| Parameter | Type | Description |
|---|---|---|
| repositoryrequired | string | GitHub repository. Accepts owner/repo or a full URL (e.g. https://github.com/owner/repo). |
Example
{
"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
| Parameter | Type | Description |
|---|---|---|
| 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
{
"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
| Parameter | Type | Description |
|---|---|---|
| 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
{
"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
| Parameter | Type | Description |
|---|---|---|
| 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
{
"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
| Parameter | Type | Description |
|---|---|---|
| urlrequired | string | The page URL to inspect. |
x_image_search
Searches royalty-free and openly licensed image libraries at once: Openverse, Wikimedia Commons, Pexels, Pixabay and Unsplash. Every result carries its license record: whether commercial use is allowed, whether credit is required, whether a copy may be hosted, and a ready-to-display credit line. Licenses are read per image, not per library. A result under a license the router does not recognize is dropped, never offered under guessed terms.
Opt in by listing x_image_search (and
x_fetch_image to download files) in x_tools
on a Responses API web_search tool; see
Enabling Server-Side Tools. Over MCP the tool
is erebine.research.image_search; see
MCP Tools. The tool exists only where
image search is enabled for your endpoint, and which libraries answer
is set by the deployment; each response reports them under
providers.
In Chat
Image search is a chat tool, enabled per workspace like the other
agentic tools: a workspace owner or operator turns on x_image_search
in the Research group of the Agentic workflows tool grid, under
Behavior in workspace settings. Enabling it enables
x_fetch_image with it, which the model uses to download a
result it may host and to register the use Unsplash requires. Deep
research turns do not use the image tools.
The research panel shows each search as a grid of thumbnails, each
with its credit line linked to the author's page and its license
linked to the license text. Select a thumbnail to open it in the image viewer.
Thumbnails load from your Erebine origin, so your browser never
contacts the image library, with one exception: Unsplash requires
its photos to be shown from its own servers, so an Unsplash
thumbnail loads from images.unsplash.com, with no
referrer. A credit that names the photographer and the library links each
to its own page. When an answer uses one of the results, the image
appears in the answer, in its own paragraph, with its credit below it.
Parameters
| Parameter | Type | Description |
|---|---|---|
| queryrequired | string | What the image should show, as search terms, for example smoked brisket on butcher paper. |
| orientationoptional | string | One of: landscape, portrait, square. Every result is re-checked against its pixel size: square is a width-to-height ratio within 10 percent of 1. Omit for any. |
| min_widthoptional | integer | Minimum full-size width in pixels, for example 1600 for a hero banner. |
| countoptional | integer | Results to return. Default 8, maximum 20. |
| licenseoptional | string | The license filter. One of: commercial, no_attribution, any_open (default). See the table below. |
| safe_searchoptional | boolean | Filter adult content. Default true. Wikimedia Commons has no adult-content filter of its own; under safe search its files are filtered by category, best effort. |
| providersoptional | string[] | Limit the search to these libraries: openverse, wikimedia, pexels, pixabay, unsplash. Omit for every library the deployment enables. |
License Filter
| Value | Admits |
|---|---|
commercial |
Licenses that permit commercial use. Credit may still be required. |
no_attribution |
Licenses that permit commercial use and require no credit. |
any_open |
Every recognized open license, non-commercial ones included. |
A library whose single license the filter rejects is not called and
is listed under providers.skipped with the reason, for
example Unsplash under no_attribution.
Libraries
Each library's collection, licenses, credit line and hosting rules are on Image Search Sources.
| Library | providers value | License | Credit required | Hosted copy | Notes |
|---|---|---|---|---|---|
| Openverse | openverse |
Creative Commons or public domain, per image | Yes, except CC0 and the Public Domain Mark | Yes | Non-commercial (NC) licenses pass only any_open. |
| Wikimedia Commons | wikimedia |
Per file. Commons accepts only free licenses, which permit commercial use | Per file | Yes | Searched by default. Under safe_search, files in a category naming adult content are dropped (best effort). Files with trademark or personality-rights restrictions are left out. |
| Pexels | pexels |
Pexels License | No | Yes | full_url is the original file. |
| Pixabay | pixabay |
Pixabay Content License | No | Yes | full_url is the large rendition, at most 1280 px on its long side. Pixabay forbids permanent hotlinking: download the file with x_fetch_image to use it. Results are cached for 24 hours, as Pixabay's API terms require. |
| Unsplash | unsplash |
Unsplash License | Yes | No | Unsplash's API guidelines require hotlinking: embed full_url as returned, and call x_fetch_image once for a photo you use; it sends the download event Unsplash requires and downloads nothing. Credit links carry Unsplash's utm_source and utm_medium=referral parameters. |
Example Tool Call (generated by model)
{
"name": "x_image_search",
"arguments": {
"query": "smoked brisket on butcher paper",
"orientation": "landscape",
"license": "commercial",
"count": 3
}
}
Response Format
| Field | Type | Description |
|---|---|---|
query |
string | The search terms. |
license |
string | The license filter applied. |
results |
object[] | The images, taken one library at a time in turn and de-duplicated by file URL. Each carries the fields below. |
providers |
object | answered (libraries that answered), failed and skipped (each entry a provider and a reason). |
notice |
string | Present when the search is degraded or empty. A degraded notice says the results come from the remaining libraries only and are not the full set. |
error |
string | Present when no library answered; the tool call is then an error. |
Result Fields
| Field | Type | Description |
|---|---|---|
provider |
string | The library, one of the providers values. |
provider_id |
string | The library's id for the image. Pass it with provider to x_fetch_image. |
title |
string | Title or description, when the library has one. |
preview_url, preview_width, preview_height |
string, integer, integer | A small rendition for previews. Sizes are present when known. |
full_url, full_width, full_height |
string, integer, integer | The largest rendition the library's API offers. Sizes are present when known. |
license_code |
string | Stable machine code, for example cc-by-sa-4.0, cc0-1.0, pexels. |
license_name |
string | Display name, for example CC BY-SA 4.0 or Pexels License. |
license_url |
string | The license text. |
commercial_use |
boolean | Whether the license permits commercial use. |
attribution_required |
boolean | Whether the license requires crediting the author. When false, credit is optional. |
can_host_copy |
boolean | Whether the terms permit storing and serving a copy of the file. When false, embed full_url as returned; x_fetch_image downloads nothing and, where the library requires it, registers the use. |
hosting_restriction |
string | Why a hosted copy is not permitted. Present only when can_host_copy is false. |
hotlink_allowed |
boolean | Whether the image's URLs may be embedded in a page. false for Pixabay, whose URLs expire and may not be hotlinked: download the file with x_fetch_image and serve your own copy. |
attribution_text |
string | Ready-to-display credit line, for example Photo by Jane Doe on Pexels, or for an open license "Title" by Author, CC BY 2.0. |
attribution_url |
string | The page the author's name in the credit line links to: the photographer's profile where the library has one (Unsplash), else the image's page. |
attribution_site, attribution_site_url |
string, string | The library the credit line names (Pexels, Pixabay, Unsplash) and the page that name links to. Absent for Openverse and Wikimedia Commons, whose credit names the work's own source. |
photographer |
string | The photographer or author, when the library names one. |
source_page |
string | The image's page on the library's site. |
Credit an image you use with its attribution_text: the
author's name linked to attribution_url and, when present,
the attribution_site name linked to
attribution_site_url. On the Responses API each
result's source_page, attribution_url and
full_url become
citation sources titled with the credit line, so a link to any of them in
the answer carries a url_citation annotation; see
Web Search.
Example Response
{
"license": "commercial",
"providers": {
"answered": ["openverse", "pexels", "unsplash"],
"failed": [],
"skipped": [
{
"provider": "wikimedia",
"reason": "it is not in the providers list"
}
]
},
"query": "smoked brisket on butcher paper",
"results": [
{
"attribution_required": true,
"attribution_text": "\"Brisket\" by jdoe, CC BY 2.0",
"attribution_url": "https://www.flickr.com/photos/jdoe/53000000000",
"can_host_copy": true,
"commercial_use": true,
"full_height": 1067,
"full_url": "https://live.staticflickr.com/65535/53000000000_0a1b2c3d4e_b.jpg",
"full_width": 1600,
"hotlink_allowed": true,
"license_code": "cc-by-2.0",
"license_name": "CC BY 2.0",
"license_url": "https://creativecommons.org/licenses/by/2.0/",
"photographer": "jdoe",
"preview_url": "https://api.openverse.org/v1/images/2f6d7c1e-8a4b-4c3d-9e2f-1a2b3c4d5e6f/thumb/",
"provider": "openverse",
"provider_id": "2f6d7c1e-8a4b-4c3d-9e2f-1a2b3c4d5e6f",
"source_page": "https://www.flickr.com/photos/jdoe/53000000000",
"title": "Brisket"
},
{
"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/",
"can_host_copy": true,
"commercial_use": true,
"full_height": 3000,
"full_url": "https://images.pexels.com/photos/1234567/pexels-photo-1234567.jpeg",
"full_width": 4000,
"hotlink_allowed": true,
"license_code": "pexels",
"license_name": "Pexels License",
"license_url": "https://www.pexels.com/license/",
"photographer": "Jane Doe",
"preview_height": 350,
"preview_url": "https://images.pexels.com/photos/1234567/pexels-photo-1234567.jpeg?auto=compress&cs=tinysrgb&h=350",
"preview_width": 467,
"provider": "pexels",
"provider_id": "1234567",
"source_page": "https://www.pexels.com/photo/brisket-1234567/",
"title": "Sliced brisket on butcher paper"
},
{
"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,
"full_height": 2667,
"full_url": "https://images.unsplash.com/photo-1600000000000-0a1b2c3d4e5f",
"full_width": 4000,
"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",
"preview_height": 267,
"preview_url": "https://images.unsplash.com/photo-1600000000000-0a1b2c3d4e5f?w=400",
"preview_width": 400,
"provider": "unsplash",
"provider_id": "Ab3dEf9GhIj",
"source_page": "https://unsplash.com/photos/Ab3dEf9GhIj?utm_source=erebine&utm_medium=referral",
"title": "brisket on a cutting board"
}
]
}
Partial Results
Each library has its own deadline. A library that fails or times out
is listed under providers.failed and does not fail the
search; notice then leads with
Search backends degraded: and says a missing image is
not evidence that none exists. When no library answers, the call is
an error. Repeated searches are served from a cache: one hour for
most libraries, 24 hours for Pixabay.
SSE Events
With vendor events on, an image search narrates as
x_research.image_searching, its query in
arguments and in metadata.query. The
x_research.result event that follows carries
metadata.count, the number of images shown, and
metadata.items, a JSON array of at most eight images,
each with title, provider,
preview_url, preview_width,
preview_height, source_page,
attribution_text, attribution_url,
license_name, license_url,
can_host_copy and hotlink_allowed. A field
with no value is left out.
data: {"type":"x_research.image_searching","name":"x_image_search","arguments":"{\"query\":\"smoked brisket on butcher paper\"}","metadata":{"query":"smoked brisket on butcher paper"}}
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
| Parameter | Type | Description |
|---|---|---|
| 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
| Surface | What 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;
sha256is the digest of those bytes.
Response Format
The body carries the same license fields as an x_image_search result, beside these:
| Field | Type | Description |
|---|---|---|
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)
{
"name": "x_fetch_image",
"arguments": {
"provider": "pexels",
"provider_id": "1234567"
}
}
Example Response
{
"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.
{
"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.
| Surface | How 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
| Parameter | Type | Description |
|---|---|---|
| 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,retryandreasonsay 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: trueand, inreason, 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
| Surface | What 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:
| Field | Type | Description |
|---|---|---|
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)
{
"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)
{
"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
| Parameter | Type | Description |
|---|---|---|
| expressionrequired | string | Mathematical expression to evaluate. Maximum 1,000 characters. |
Supported Operations
| Category | Supported |
|---|---|
| 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
{
"name": "x_calculator",
"arguments": {
"expression": "10000 * (1 + 0.05)^3"
}
}
Example Response
{
"expression": "10000 * (1 + 0.05)^3",
"result": 11576.25
}
More Examples
| Expression | Result |
|---|---|
sqrt(144) + 2^3 | 20.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
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
| Parameter | Type | Description |
|---|---|---|
| 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
{
"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
| Parameter | Type | Description |
|---|---|---|
| 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
| Field | Contents |
|---|---|
location | Name, region, country, coordinates, IANA time zone and local time. |
current | Temperature, 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. |
today | High, low, condition, precipitation, sunrise and sunset. |
hourly | The next 24 hours. |
daily | Up to 7 days after today, each with high, low, condition, precipitation, sunrise and sunset. |
alerts | Official alerts in effect, in the United States. Elsewhere alerts_note says no official alert source is checked. |
sources | Each data source used, with the credit its terms ask for. |
summary | One 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
{
"name": "x_get_weather",
"arguments": {
"place": "Kyoto",
"include": ["current"]
}
}
Example Response
{
"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
| Parameter | Type | Description |
|---|---|---|
| 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 Type | Use For |
|---|---|
text/markdown | Markdown documents, reports, notes |
text/html | HTML pages, interactive previews |
text/plain | Plain text files, configuration |
image/svg+xml | SVG vector graphics |
text/x-mermaid | Mermaid diagram definitions |
application/json | JSON 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
{
"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
{
"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
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
| Parameter | Type | Description |
|---|---|---|
| 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
{
"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
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
| Parameter | Type | Description |
|---|---|---|
| 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
| Field | Type | Description |
|---|---|---|
| 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:
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
{
"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
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
| Parameter | Type | Description |
|---|---|---|
| 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.
{
"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"
}
}
{
"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.
{
"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
| Parameter | Type | Description |
|---|---|---|
| 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
{
"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
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
| Parameter | Type | Description |
|---|---|---|
| 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)
| Field | Type | Description |
|---|---|---|
| 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.
{
"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.
{
"name": "x_ask_user",
"arguments": {
"question": "This will overwrite the existing configuration. Proceed?",
"style": "confirm"
}
}
Rating Style
A 1-5 rating scale.
{
"name": "x_ask_user",
"arguments": {
"question": "How satisfied are you with this solution?",
"style": "rating"
}
}
Form Style
Labeled input fields for collecting structured data.
{
"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.
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
| Parameter | Type | Description |
|---|---|---|
| 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
| Parameter | Type | Description |
|---|---|---|
| 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
{
"name": "x_save_memory",
"arguments": {
"content": "User prefers TypeScript with strict mode enabled for all code examples",
"category": "preference"
}
}
Example Response
{
"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
| Parameter | Type | Description |
|---|---|---|
| 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
{
"name": "x_recall_memory",
"arguments": {
"query": "What programming language does the user prefer?"
}
}
Example Response
{
"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
| Parameter | Type | Description |
|---|---|---|
| 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
{
"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
- Model response, The model generates a response that may include one or more tool calls.
-
Tool execution, Erebine executes the requested
tools server-side (e.g.,
x_web_search,x_fetch_url,x_code_search). - Result injection, Tool results are appended to the conversation as tool-role messages.
- Follow-up, The model generates another response based on the tool results. This response may include additional tool calls.
- Termination, Steps 2-4 repeat until the model produces a final text response (no tool calls) or the iteration limit is reached.
Limits
| Limit | Value | Description |
|---|---|---|
| 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:
| Value | Behavior |
|---|---|
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:
- A turn that does not opt into vendor events is always
off. Research never runs on a plain OpenAI-compatible request. - An explicit
research_depthfield on the request wins. An unrecognized value is ignored, and the next rule applies. - Otherwise the workspace
research_depthpreference applies. - 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.
{
"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.
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.
| Field | Description |
|---|---|
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 Type | Description |
|---|---|
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
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 Type | Tool | Description |
|---|---|---|
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 Type | Description |
|---|---|
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 Type | Description |
|---|---|
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 Type | Description |
|---|---|
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 Type | Description |
|---|---|
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
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
{
"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
| Limit | Value | Description |
|---|---|---|
| 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 -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 -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"
]
}
]
}'
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)
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 -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}
}
]
}'
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)
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 -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"]
}
]
}'
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()
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 -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)
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()
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 -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"]
}
]
}'
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()
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();