Y2 Elite workspaces are rolling out for teams
Y2Y2Docs

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.

EndpointStream formatChoose it when
POST /agent-y2/chat/streamVercel AI SDK UI message streamYour client understands the native AI SDK protocol
POST /chat/completionsOpenAI-style chat.completion.chunk server-sent eventsYour 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

Terminal
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:

request.json
{
  "threadId": "j57...",
  "messages": [
    {
      "role": "user",
      "parts": [{ "type": "text", "text": "Which entities should I watch next?" }]
    }
  ]
}

Send an OpenAI-compatible request

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

Terminal
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 stateContext used by Agent Y2
No threadIdCreates an API-source thread and uses non-empty user and assistant text from the supplied transcript
Existing threadIdVerifies the same user, API source, and workspace, then loads up to 40 persisted messages from that thread
Latest user messageSaved to the thread and used as the new prompt
System, developer, or tool transcript entries without toolsAccepted for compatibility but excluded from the fixed Copilot prompt
Non-empty tools arrayUses 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 categoryAvailability
Y2 documentation searchAlways registered
Public briefing search and followRegistered for standard Agent Y2 sessions
News searchRegistered for standard sessions
Web searchRequires the workspace web-search entitlement
Profile creation and editingRequires remaining custom-profile capability and metering context
OSINT searchRequires OSINT entitlement
Y2 Global Knowledge retrievalRequires Chat entitlement. Searches only authorized shared and key-workspace corpora
Cyber, FININT, markets, entity, incident, and investigation toolsAdded according to the related intelligence entitlements
Image generationRequires 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"
  }
}
FieldMaximumCurrent behavior
source128 charactersAccepted for compatibility. The thread source is still recorded as api
externalUserId256 charactersAccepted but not currently persisted to the thread
externalThreadId256 charactersStored 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 scopePer minutePer day
API key5100
User or workspace aggregate10250

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

StatusCommon causeResponse
400Invalid JSON, missing latest user text, unsupported alias, invalid tool schema or history, invalid thread ID, or native modelId, isOnboarding, or attachmentsCorrect the request. Do not retry unchanged
401Missing, malformed, revoked, or invalid API keyReplace or rotate the credential
402Subscription, workspace Agent Y2 credit, or upstream provider credit exhaustionCheck the workspace plan and Agent Y2 credit balance. Do not start x402 handling
403Missing scope, no chat entitlement, blocked access, or unauthorized threadCheck key scope, workspace, plan, and thread origin
404Supplied thread no longer existsStart a new thread or correct the stored ID
429Normal API or shared Agent Y2 limit exceededBack off for Retry-After seconds
500Stream preparation or provider execution failedRetry with backoff and retain X-Request-Id for support