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, chat credit budget, 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 402 response from these routes describes plan, chat-credit, or upstream-provider credit exhaustion; 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-delta chunks, a final chunk with finish_reason: "stop", 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.

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.

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.

Error guide

Related reference