Agent Y2 API
Stream Y2's preconfigured workspace-aware agent through native or OpenAI-compatible requests
Use either streaming endpoint to run the Y2 copilot. Requests use the key's workspace, plan, credits, thread history, and allowed tools.
Model and tool selection
API callers cannot select an arbitrary model, enable onboarding mode, or attach files in v1. The
model value on the OpenAI-compatible route is a Y2 routing alias, not model selection. Requests
without client tools use the fixed Agent Y2 Copilot instructions. A non-empty tools array
selects the isolated client-harness contract described below.
Choose an endpoint
Both endpoints use https://api.y2.dev/api/v1.
| Endpoint | Stream format | Choose it when |
|---|---|---|
POST /agent-y2/chat/stream | Vercel AI SDK UI message stream | Your client understands the native AI SDK protocol |
POST /chat/completions | OpenAI-style chat.completion.chunk server-sent events | Your client already consumes streaming chat completions |
The routes share the same rate-limit quota. Switching formats does not increase it.
Create a scoped key
Create a key with agent:y2 in the workspace that owns the threads and tool actions.
Keep the key in a server or local runtime.
Agent Y2 does not support x402. 402 INSUFFICIENT_CREDITS means the workspace's Agent Y2 balance is exhausted.
Send a native request
curl -N -i "https://api.y2.dev/api/v1/agent-y2/chat/stream" \
-H "Authorization: Bearer $Y2_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"role": "user",
"parts": [
{ "type": "text", "text": "What changed in cyber risk this week?" }
]
}
],
"metadata": {
"source": "customer_crm",
"externalThreadId": "case-123"
}
}'The response is an AI SDK UI message stream. API responses omit internal reasoning parts even though the in-app stream can include them.
Read the X-Thread-Id response header and store it. Continue the conversation by sending that ID
in the next native request body:
{
"threadId": "j57...",
"messages": [
{
"role": "user",
"parts": [{ "type": "text", "text": "Which entities should I watch next?" }]
}
]
}Send an OpenAI-compatible request
curl -N -i "https://api.y2.dev/api/v1/chat/completions" \
-H "Authorization: Bearer $Y2_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "y2-agent",
"stream": true,
"messages": [
{
"role": "user",
"content": "Summarize the latest Y2 platform capabilities."
}
]
}'The compatibility route requires stream: true. model is optional. When supplied, it must be
y2-agent or agent-y2. It emits a role chunk, text or tool-call delta chunks, a final chunk with
finish_reason: "stop" or "tool_calls", and data: [DONE].
To continue a conversation, pass threadId in the JSON body or send the prior ID in an
X-Thread-Id request header.
Client tools run only in your harness
Supplying a non-empty tools array switches this request to client-harness mode. Y2 sends the
schemas to the model and streams function calls back, but it never executes those functions.
Your client remains responsible for permission checks, local execution, and returning matching
tool results. Agent Y2's server-side intelligence tools are not exposed in this mode.
Use client-side tools
Client-harness mode preserves system and developer instructions, assistant tool calls, and matching tool results. This is the mode used by the native Y2 CLI for repository instructions, local file operations, commands, skills, and subagents.
curl -N -i "https://api.y2.dev/api/v1/chat/completions" \
-H "Authorization: Bearer $Y2_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "y2-agent",
"stream": true,
"messages": [
{ "role": "system", "content": "Inspect the workspace before editing." },
{ "role": "user", "content": "Read README.md." }
],
"tools": [
{
"type": "function",
"function": {
"name": "read_file",
"description": "Read a workspace file",
"parameters": {
"type": "object",
"properties": { "path": { "type": "string" } },
"required": ["path"]
}
}
}
],
"tool_choice": "auto"
}'The response header X-Y2-Agent-Mode: harness confirms that the client-tool contract was selected.
Tool definitions are limited to 128 functions. Names, descriptions, schemas, transcript length, and
tool arguments are bounded. Malformed or unmatched tool history returns 400 before model execution.
Understand thread context
| Request state | Context used by Agent Y2 |
|---|---|
No threadId | Creates an API-source thread and uses non-empty user and assistant text from the supplied transcript |
Existing threadId | Verifies the same user, API source, and workspace, then loads up to 40 persisted messages from that thread |
| Latest user message | Saved to the thread and used as the new prompt |
System, developer, or tool transcript entries without tools | Accepted for compatibility but excluded from the fixed Copilot prompt |
Non-empty tools array | Uses client-harness mode with supplied instructions and complete matching tool history |
A thread created in the app cannot be continued through the API. A workspace-scoped API key also cannot continue a thread from another workspace.
An invalid ID returns 400. A missing thread returns 404. A thread outside the allowed source, user, or workspace returns 403.
Available tools
The exact tool set is assembled for every request from current workspace entitlements.
| Tool category | Availability |
|---|---|
| Y2 documentation search | Always registered |
| Public briefing search and follow | Registered for standard Agent Y2 sessions |
| News search | Registered for standard sessions |
| Web search | Requires the workspace web-search entitlement |
| Profile creation and editing | Requires remaining custom-profile capability and metering context |
| OSINT search | Requires OSINT entitlement |
| Y2 Global Knowledge retrieval | Requires Chat entitlement. Searches only authorized shared and key-workspace corpora |
| Cyber, FININT, markets, entity, incident, and investigation tools | Added according to the related intelligence entitlements |
| Image generation | Requires image-generation entitlement and a compatible selected agent path |
Available tools still require workspace permissions and sufficient resources. The agent chooses which tools to call. This table applies to Copilot mode. In client-harness mode, your client executes the supplied tools.
Agent Y2 uses its existing agent:y2 scope when it invokes Y2 Global Knowledge. Do not add
intel:knowledge to an Agent Y2 key unless the same integration also calls the direct retrieval
endpoint. Direct retrieval and agent execution are separate least-privilege surfaces.
Metadata behavior
Both routes accept a strict metadata object:
{
"metadata": {
"source": "ops_console",
"externalUserId": "analyst-42",
"externalThreadId": "case-123"
}
}| Field | Maximum | Current behavior |
|---|---|---|
source | 128 characters | Accepted for compatibility. The thread source is still recorded as api |
externalUserId | 256 characters | Accepted but not currently persisted to the thread |
externalThreadId | 256 characters | Stored when Y2 creates a new thread. It does not replace the Y2 threadId |
Unknown metadata properties fail strict validation. Keep your own correlation log and never put secrets or full customer records in metadata.
Provider privacy controls
The current Agent Y2 executor selects chat models marked as Zero Data Retention capable and sends
OpenRouter provider options with zdr: true and data_collection: "deny".
These controls govern the external model request. Y2 still stores API-source threads, messages, request attribution, tool results, and usage records under Y2's product data lifecycle. See the Privacy Policy for the customer-facing data terms.
Rate limits and response headers
Agent Y2 applies these limits in addition to the API key's normal plan limits:
| Limit scope | Per minute | Per day |
|---|---|---|
| API key | 5 | 100 |
| User or workspace aggregate | 10 | 250 |
Inspect Retry-After, the normal X-RateLimit-* headers, and the
X-Y2-Agent-RateLimit-* headers. Successful streams also return X-Thread-Id, X-Y2-Agent: y2,
and X-Y2-Agent-Mode: copilot or X-Y2-Agent-Mode: harness.
Error guide
| Status | Common cause | Response |
|---|---|---|
400 | Invalid JSON, missing latest user text, unsupported alias, invalid tool schema or history, invalid thread ID, or native modelId, isOnboarding, or attachments | Correct the request. Do not retry unchanged |
401 | Missing, malformed, revoked, or invalid API key | Replace or rotate the credential |
402 | Subscription, workspace Agent Y2 credit, or upstream provider credit exhaustion | Check the workspace plan and Agent Y2 credit balance. Do not start x402 handling |
403 | Missing scope, no chat entitlement, blocked access, or unauthorized thread | Check key scope, workspace, plan, and thread origin |
404 | Supplied thread no longer exists | Start a new thread or correct the stored ID |
429 | Normal API or shared Agent Y2 limit exceeded | Back off for Retry-After seconds |
500 | Stream preparation or provider execution failed | Retry with backoff and retain X-Request-Id for support |