Agent Y2 API

Agent Y2 exposes the same preconfigured intelligence agent used by the Y2 copilot through two API-key-authenticated streaming endpoints. It uses the key's workspace, plan entitlements, shared Agent Y2 credit balance, persisted thread history, and allowed Y2 tools.

Choose an endpoint

Both endpoints use https://api.y2.dev/api/v1.

The routes share the same Agent Y2-specific rate-limit pool. Switching formats does not create a second quota.

Create a scoped key

Agent Y2 does not support x402. A Y2 402 with code INSUFFICIENT_CREDITS means the workspace's shared Agent Y2 balance is exhausted; it is not a payment challenge.

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.

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

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.

The server returns 400 for an invalid ID shape, 404 for a missing thread, and 403 when the thread exists outside the caller's allowed source, user, or workspace scope.

Available tools

The exact tool set is assembled for every request from current workspace entitlements.

Tool availability does not guarantee that the agent will call a tool. Tool actions still enforce the underlying workspace permissions and resource limits. This table applies to Copilot mode; client-harness mode advertises only the caller's function schemas and executes none of them on Y2.

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"
  }
}

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:

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

Related reference