---
title: "OpenAI-compatible Agent Y2 chat stream"
description: "Routes OpenAI-style chat completions requests to Agent Y2 and streams text or client-side tool-call responses to compatible clients. v1 supports `messages`, `stream: true`, optional `model` set to `y2-agent` or `agent-y2`, optional `threadId`, optional bounded `metadata`, and bounded OpenAI function tools. Arbitrary models are unsupported. Without client tools, Agent Y2 keeps its fixed Copilot instructions and Y2 tools. A non-empty `tools` array selects harness mode. System and developer messages become client instructions. Tool-call history is preserved. The client executes returned tool calls. v1 requires an API key and does not support x402. Both Agent Y2 routes share a throttle of 5 requests/minute and 100/day per key, plus 10 requests/minute and 250/day per user or workspace. A `402` indicates subscription, Agent Y2 credit, or upstream-provider credit exhaustion, not an x402 challenge."
canonical: https://y2.dev/docs/api/reference/agent-y2/createY2OpenAIChatCompletion/
---

Endpoint Reference[Agent Y2](https://y2.dev/docs/api/reference/agent-y2)

# OpenAI-compatible Agent Y2 chat stream

Routes OpenAI-style chat completions requests to Agent Y2 and streams text or client-side tool-call responses to compatible clients. v1 supports \`messages\`, \`stream: true\`, optional \`model\` set to \`y2-agent\` or \`agent-y2\`, optional \`threadId\`, optional bounded \`metadata\`, and bounded OpenAI function tools. Arbitrary models are unsupported. Without client tools, Agent Y2 keeps its fixed Copilot instructions and Y2 tools. A non-empty \`tools\` array selects harness mode. System and developer messages become client instructions. Tool-call history is preserved. The client executes returned tool calls. v1 requires an API key and does not support x402. Both Agent Y2 routes share a throttle of 5 requests/minute and 100/day per key, plus 10 requests/minute and 250/day per user or workspace. A \`402\` indicates subscription, Agent Y2 credit, or upstream-provider credit exhaustion, not an x402 challenge.

`POST https://api.y2.dev/api/v1/chat/completions`

- Operation ID: `createY2OpenAIChatCompletion`
- Required scopes: `agent:y2`
- Contract: https://y2.dev/openapi.json

## Request body

`application/json`: `OpenAICompatibleChatCompletionRequest` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | `y2-agent`, `agent-y2` | No | Optional Y2 Agent model alias. Arbitrary model selection is not supported. |
| `messages[]` | array of `OpenAICompatibleChatMessage` | Yes |  |
| `messages[].role` | `system`, `developer`, `user`, `assistant`, `tool` | Yes | System, developer, and tool messages are used only when the request supplies a non-empty `tools` array. |
| `messages[].content` | string or array of `AgentY2TextPart` or null | Yes |  |
| `messages[].tool_calls[]` | array of object | No |  |
| `messages[].tool_call_id` | string | No |  |
| `messages[].name` | string | No |  |
| `stream` | boolean | Yes |  |
| `threadId` | string | No | Optional Y2 thread ID. The `X-Thread-Id` request header is also accepted. |
| `metadata` | `AgentY2RequestMetadata` | No |  |
| `metadata.source` | string | No |  |
| `metadata.externalUserId` | string | No |  |
| `metadata.externalThreadId` | string | No |  |
| `tools[]` | array of `OpenAICompatibleFunctionTool` | No | A non-empty array selects client harness mode. Y2 never executes these tools server-side. |
| `tools[].type` | string | Yes |  |
| `tools[].function` | object | Yes |  |
| `tool_choice` | `auto`, `none`, `required` | No |  |
| `parallel_tool_calls` | boolean | No |  |
| `max_tokens` | integer | No |  |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | OpenAI-style streaming chat completion chunks |  |
| 400 | Invalid request parameters |  |
| 401 | Missing or invalid API key |  |
| 402 | Agent Y2 subscription, workspace Agent Y2 credit, or provider credit exhaustion |  |
| 403 | Insufficient permissions or access denied |  |
| 429 | Rate limit exceeded (per-key or per-account aggregate) |  |
| 500 | Internal server error |  |
