Build with clarity.

Where we are

The API is built and tested. Until the first model route opens, chat requests return 503 inference_not_configured. The live state is always at https://undergrove.vercel.app/api/status.

It follows the OpenAI API format, so existing SDKs work by changing the base URL: chat with images, function calling and structured outputs, plus embeddings, transcription and speech. To keep requests unreadable even to our gateway, use encrypted mode, as the workspace does.

Quickstart

Base URL: https://undergrove.vercel.app/v1. List models with GET /v1/models, then stream a reply:

curl https://undergrove.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "stream": true,
    "messages": [{"role": "user", "content": "Help me explore an idea."}]
  }'

Playground

Send a chat request from this page with your own key, and see the answer, its usage and the raw response, with the same request as curl. It goes from your browser to this site’s /v1, like any other API call, and spends your allowance or credit as usual.

Choose Encrypted to send it the way the SDKs’ encrypted mode does: Tinfoil’s SDK verifies the enclave in this page, then seals the request to it. The playground shows the bytes that actually left the page, what came back, and the receipt for the enclave it was sealed to.

curl --no-buffer https://undergrove.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "messages": [
      {
        "role": "user",
        "content": "Help me explore an idea."
      }
    ],
    "stream": true
  }'

Authentication

Send an Undergrove API key as a Bearer token. Keys start with ugk_ and are issued by invitation during the alpha. Where self-serve keys are switched on, alpha members create up to five in the workspace settings, and each spends its account’s allowance and credit. We store only a one-way hash of each key, so a lost key can’t be recovered, only replaced.

Each self-serve key can have its own limits, set when it’s created or later in the settings: a daily spending cap, after which its requests are refused until midnight UTC, and a list of the models it may use. A capped key still counts against its account’s allowance. Keys made before limits existed have none and keep working as before.

curl https://undergrove.vercel.app/v1/models \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY"

Endpoints

Responses use the standard chat.completion shape. Streams send chat.completion.chunk events and end with data: [DONE]. Reasoning models stream their reasoning separately in delta.reasoning_content, and the last chunk reports token usage. If a stream is interrupted, the final event is an error object instead of [DONE], so a partial answer is never mistaken for a complete one.

curl https://undergrove.vercel.app/v1/embeddings \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "undergrove/nomic-embed-text",
    "input": ["Where is the signed contract?", "Payment terms"]
  }'

Parameters

curl https://undergrove.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "max_tokens": 500,
    "messages": [{"role": "user", "content": "Is it raining in Lisbon?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }]
  }'

Encrypted mode

The standard API is read by our gateway in memory to check each request. To keep requests unreadable to Undergrove as well, use Tinfoil’s SDK with your key. It verifies the enclave’s hardware attestation, then encrypts each request so only that enclave can read it. Our relay checks your key and allowance and passes the ciphertext on.

import { SecureClient } from "tinfoil"; // npm install tinfoil

const RELAY = "https://undergrove.vercel.app/api/enclave";
const client = new SecureClient({
  baseURL: `${RELAY}/v1/`,
  attestationBundleURL: RELAY,
});
await client.ready(); // verifies the enclave; throws if it can't

const response = await client.fetch("chat/completions", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.UNDERGROVE_API_KEY}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "gemma4-31b", // enclave_model in /v1/models
    max_tokens: 1000,
    messages: [{ role: "user", content: "Summarise this contract." }],
  }),
});
console.log((await response.json()).choices[0].message.content);

The same client reaches embeddings, audio/transcriptions and audio/speech. Because the relay can’t read these requests, models are named by their enclave_model id from /v1/models, answers come back in Tinfoil’s format, and usage is estimated from the size of the encrypted data. Allowances and credit apply as usual.

MCP server

Undergrove is also a Model Context Protocol server, at https://undergrove.vercel.app/mcp. Each live model is a tool, such as ask_<model>, that MCP clients like Claude Code, Cursor and Claude Desktop can call with your API key. A tool takes a prompt, and optionally system, max_tokens and, for models that search, web_search, and returns the model’s answer as text.

A tool call is an API request like any other: the gateway reads it in memory, sends it on the model’s published route, keeps no copy, and counts it against your key’s limits, allowance and credit. The server uses streamable HTTP, answers in JSON and keeps no sessions. It speaks protocol versions 2025-11-25, 2025-06-18 and 2025-03-26.

claude mcp add --transport http undergrove https://undergrove.vercel.app/mcp \
  --header "Authorization: Bearer ugk_your_key"

{
  "mcpServers": {
    "undergrove": {
      "url": "https://undergrove.vercel.app/mcp",
      "headers": {
        "Authorization": "Bearer ugk_your_key"
      }
    }
  }
}

{
  "mcpServers": {
    "undergrove": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://undergrove.vercel.app/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ugk_your_key"
      }
    }
  }
}

curl https://undergrove.vercel.app/mcp \
  -H "Authorization: Bearer ugk_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Then call a model’s tool:

curl https://undergrove.vercel.app/mcp \
  -H "Authorization: Bearer $UNDERGROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "ask_<model>",
      "arguments": {"prompt": "Name three uses for a sealed envelope."}
    }
  }'

The other way round, the workspace can use tools from MCP servers you connect in Settings. Those calls go through Undergrove’s server to the server you connected, in plaintext, so use servers you trust with what the tools are given.

Errors and limits

Errors use the OpenAI format: {"error": {"message", "type", "code"}}.

During the alpha, each key or account has a per-minute, daily request and daily spending allowance. Current values are published at /api/status.

HTTP/2 429
retry-after: 41

{
  "error": {
    "message": "You’re sending messages quickly. Please wait a moment.",
    "type": "rate_limit_error",
    "code": "rate_limited"
  }
}

Know where your data goes

The gateway checks your key, applies limits, and forwards only the fields above to the model route. It keeps no copy of prompts or answers and does not log them. Its logs record route names, status codes, and timings only. Rate-limit counters use a one-way hash of your key or account and expire within two days.

Each model route’s operator, location, and retention are published in the model register at /api/status and on the privacy page. Requests never fall back to a different route. Vercel, our host, keeps standard request metadata such as IP addresses.

On confidential-computing routes, the API gateway verifies the enclave’s hardware attestation before connecting and encrypts each request so only that enclave can read it. The gateway itself still reads API requests in memory to check them.

Workspace data

Sync, shared links and shared projects store only ciphertext the browser made. Each diagram shows who holds the key, step by step.

What verification proves

Before sending anything, the workspace runs Tinfoil’s open-source verifier in your browser. It checks the enclave’s hardware attestation report against AMD’s or Intel’s signing keys, checks that the code measured in the enclave matches a release Tinfoil published and signed on GitHub, and checks that the encryption key it uses belongs to that enclave. Select Verified in the workspace to see each check, the release and the measurement.

It proves that your messages can only be decrypted by that hardware running that published code. It does not prove the published code is free of flaws, protect against weaknesses in the processors themselves, or cover what you do with answers after they reach your browser. The workspace code is served by Undergrove, so you are trusting us to serve the verifier as published; Verify this page compares the code your browser loaded with the build’s manifest, and npm run verify:site compares the site with your own build of the same commit. An independent assessment is planned.

Each answer from an enclave has a Receipt button. It shows the enclave, release and measurements verified before that request was sent and the key it was encrypted to, and downloads them as JSON. Until the tab closes, the download includes the attestation report, so you can run the verifier on it again later; after that, it has the report’s hash and where to fetch the enclave’s current one. The receipt is your browser’s record, not a signed statement, and the enclave it names is Tinfoil’s model router; the router passes requests on to the model’s own enclave. The receipt names that enclave too, and your browser tries to verify it the same way. Most model enclaves run on Intel TDX, which the browser verifier can’t check yet; for those the receipt says so, and the check rests on the router, whose published code verifies each model enclave before using it.

# The attestation bundle the gateway verified, what it checked
# in it, and the steps to check it again yourself
curl https://undergrove.vercel.app/v1/attestation

What’s next