---
title: "Agent Y2 API"
description: "Stream Y2's preconfigured workspace-aware agent through native or OpenAI-compatible requests"
canonical: https://y2.dev/docs/api/agent-y2/
---

# 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](https://y2.dev/docs/api/create-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 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](https://y2.dev/privacy) 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                         |

## Related reference

[Generated Agent Y2 reference](https://y2.dev/docs/api/reference/agent-y2): Verify the exact request schemas, response headers, and generated examples

[Authentication](https://y2.dev/docs/api/authentication): Understand key format, scopes, tenant resolution, and plan limits

[MCP setup](https://y2.dev/docs/api/mcp): Connect an MCP-compatible agent to Y2's exposed tools
