Start here for developers

Step 1 — Find the open doors (2 minutes)

Start with GET /api/v1. It needs no key and lists the doors open right now, with each door's method, url, auth, limit_per_minute and docs link.

Run this in a Bash terminal. Keep the same terminal for the next steps:

BASE=https://app.netshow.ai
curl --max-time 30 \
  "$BASE/api/v1" \
  -H 'Accept: application/json'

The index answers only while ai.features.developer_surface_v1 is on. A 404 means the developer surface is off; ask the administrator before continuing. A registered route is not a promise that its switch is on.

In the JSON, find the agent.mcp door for step 2 and the mcp.server door for step 3. Follow the returned paths and limits. If a door is absent, it is not open. The MCP guide and public agent API guide explain those doors in more detail.

Step 2 — Ask a public agent, with no key (3 minutes)

Use POST /api/agent/{slug}/mcp with the ask tool. Choose an agent from the public directory, open its page and copy its slug: in /agent/{slug}, the slug is the last part of the address. It must be an agent whose owner has published it, not a private agent. Enter that slug below; do not enter the braces.

read -r -p 'Slug: ' SLUG
CT=Content-Type
curl --max-time 30 \
  "$BASE/api/agent/$SLUG/mcp" \
  -H "$CT: application/json" \
  --data-binary @- <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ask",
    "arguments": {
      "question":
        "What do you offer?"
    }
  }
}
JSON

Read the answer in result.content; result.structuredContent describes its source and status. Change question to ask about that agent's published knowledge. No account or key is needed, and this call does not send a booking or message to anyone.

The door needs ai.features.agent_ready_sites. Real answers from published knowledge also need ai.features.public_agent_answers; without it, the door returns discovery information rather than a knowledge answer. A 404 can mean the door is off or the slug is not public. An HTTP 200 can still contain a JSON-RPC error: read the body before calling it a success.

Step 3 — Make a key and connect your client (5 minutes)

When ai.features.developer_keys_page is on, sign in and open /dashboard/developers to manage your NetShow tokens and A2A keys. For the MCP client below, choose a NetShow MCP connection token; an A2A key is for the A2A doors.

If that page is unavailable, open your agent from your agents, and choose MCP connection, the card headed “Use this agent inside Claude”. Press Create connection and copy the token once. It lasts 30 days. The card needs ai.features.mcp_owner_connect_card; if it is unavailable, ask the administrator.

Use POST /api/mcp for the authenticated server. This Bash sample reads your token without echoing it or putting it in shell history, then checks the MCP handshake:

read -rs -p 'Token: ' TOKEN
AUTH="Bearer $TOKEN"
printf '\n'
curl --max-time 30 \
  "$BASE/api/mcp" \
  -H "Authorization: $AUTH" \
  -H "$CT: application/json" \
  --data-binary @- <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "initialize",
  "params": {
    "protocolVersion":
      "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "quickstart",
      "version": "1.0.0"
    }
  }
}
JSON
unset TOKEN AUTH

A successful reply contains result.protocolVersion, result.capabilities and result.serverInfo. A 401 means the token is missing, invalid or expired. Use an MCP connection token here; an A2A key or harness pairing token is a different credential.

In Claude, ChatGPT or Cursor, add a remote MCP connection with the server URL https://app.netshow.ai/api/mcp. In a client that accepts a bearer token, put your token in its private authorization field. If the client requires OAuth instead, use that sign-in flow only when the index advertises OAuth discovery; do not paste a token into the URL. Client support varies. The MCP guide and owner connection guide cover the connection choices.

When both ai.features.mcp_oauth_connect and ai.features.dev_surface_oauth_api_read are on, the index's auth description for api.me also names api:read. An OAuth client may request mcp api:read to use its one-hour token on the read-only /api/v1 doors as well as MCP. That scope does not allow POST /api/v1/agents/{slug}/ask; use the no-key REST sample in step 4 for that door.

Let your client finish initialize, send notifications/initialized, then request tools/list. Choose a returned tool and use its input schema for tools/call. The terminal sample above verifies the handshake; it does not replace the client's full connection sequence. Never share a real token in documentation, tickets or logs.

Step 4 — Ask over /api/v1 and check your quota (when open)

When the index lists the agent.ask door, POST /api/v1/agents/{slug}/ask is the plain REST twin of step 2: send JSON with a question, get back answer, sources, the agent's page, its AI disclosure and your quota for today. No key is needed; without one the call counts against the shared daily quota of your address, and with your token (Bearer) against your own key. Run it in the same terminal as step 2:

QUESTION='{"question": "What do you offer?"}'
printf '%s' "$QUESTION" | curl --max-time 30 \
  "$BASE/api/v1/agents/$SLUG/ask" \
  -H "$CT: application/json" \
  -H 'Accept: application/json' \
  --data-binary @-

GET /api/v1/me answers what your key is: its kind, abilities, the agent it belongs to, its per-minute and per-day limits and how many requests it has left today (401 without a key). Every /api/v1 answer carries X-Quota-Limit and X-Quota-Remaining; past the quota a door answers 429 with Retry-After until midnight UTC.

The index also lists GET /api/v1/changes: read it for revisions, newest first, and any announced retirement date. It needs no key and only the ai.features.developer_surface_v1 switch, so it remains available when the ask and me doors are off.

The ask and me doors need ai.features.dev_surface_v1_agent_ask beside ai.features.developer_surface_v1; the ask door also needs ai.features.public_agent_answers and the ai.spend.lanes.developer_api.daily_ceiling_usd lane above 0. While that lane is closed the ask door answers 503 developer_api_budget_closed and spends nothing.

Three runnable examples sit in the repository under docs/developer/examples: an A2A client in Python (standard library only, with its own offline test), NetShow agents inside Claude over MCP, and a GPT Action built from a one-operation OpenAPI file for the ask door.

Switches

The index and public-agent doors answer 404 while their switches are off. The connection card is also off until your administrator turns it on. Discover what is open in step 1; each linked guide explains its own switches. This quickstart does not turn anything on.

Limits and spending

The index and authenticated MCP server allow 60 requests per minute; the public-agent MCP door allows 30. On 429, wait for Retry-After before trying again. Every curl above stops after 30 seconds.

Public discovery spends nothing. Public-agent answers use published passages when their model lane is closed; an owner may allow model wording under the public_agent_answers daily ceiling. Authenticated tools still enforce the owner's permissions, approvals and spending limits. NetShow never spends without a ceiling: each paid lane has a daily ceiling in US dollars; 0 means closed. A closed or exhausted lane refuses execution.

For owners

You can connect your agent without writing code: Add your agent to ChatGPT or Claude. Need an agent first? Create an agent, then put it on your website.

For another route into NetShow, read the live widget, the agent creator, the harness, harness runs, tools and costs, the harness router, or A2A.

Your agent always says it is an AI, on every door, in every language.