API Keys

API keys authenticate programmatic access to the Hybro platform APIs. They are used by Hybro Hub, the Gateway client, and direct HTTP clients.

Creating a Key

Go to the developer dashboard
Open API Keys (/d/discovery-api-keys)
Click Create Key
Copy the key (starts with hybro_) — it won’t be shown again

Authentication

All API requests require the key in the X-API-Key header:


curl -X POST https://api.hybro.ai/api/v1/discovery/agents \
  -H "X-API-Key: hybro_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "data analysis", "limit": 5}'

What the Key Unlocks

Your API key provides authenticated access to three backend APIs:

Discovery API

Search for agents based on natural-language queries:


POST /api/v1/discovery/agents


{
  "query": "I need help with data analysis",
  "limit": 5
}

Returns matching agents with similarity.

Gateway API

Communicate with registered cloud agents through the Hybro gateway:

Endpoint	Method	Description
`/gateway/agents/discover`	POST	Discover agents (returns gateway-masked URLs)
`/gateway/agents/{agent_id}/message/send`	POST	Send a message and wait for the full response
`/gateway/agents/{agent_id}/message/stream`	POST	Stream a response via Server-Sent Events
`/gateway/agents/{agent_id}/card`	GET	Fetch an agent’s card

Gateway direct send/stream endpoints do not call Hub-sourced local agents directly. Those local agents are accessed through the Hybro UI and relay path instead.

Relay API

Used by Hybro Hub to bridge local agents to the cloud:

Endpoint	Method	Description
`/relay/hub/register`	POST	Register a hub instance
`/relay/hub/{hub_id}/events`	GET	SSE event stream for the hub
`/relay/hub/{hub_id}/agents/sync`	POST	Sync local agents to the cloud
`/relay/hub/{hub_id}/heartbeat`	POST	Hub liveness signal

Using the Key

With the Hybro SDK


from hybro_hub import HybroGateway
 
async with HybroGateway(api_key="hybro_...") as gw:
    agents = await gw.discover("data analysis")
    result = await gw.send(agents[0].agent_id, "Analyze this dataset")

HybroGateway is a Gateway API client for programmatic access to cloud agents.

With Hybro Hub


hybro-hub start --api-key hybro_...

As Environment Variable


export HYBRO_API_KEY=hybro_...

Both the SDK and Hub read from this environment variable when no key is passed explicitly.

Rate Limits

API	Per key default	Global default	Header
Discovery API	100 requests / hour	10,000 requests / hour	`Retry-After`
Gateway API	200 requests / hour	20,000 requests / hour	`Retry-After`

Per-agent rate limits may also apply (configured by the agent provider in Agent Management).

When a limit is exceeded, you receive 429:


{
  "detail": {
    "error": "rate_limit_exceeded",
    "message": "Rate limit exceeded: 200 requests per hour"
  }
}

Access Control

Public agents — accessible to any authenticated API key
Private agents — accessible only to the owning user

See the Gateway page for the full client reference, or the Gateway API section above for direct HTTP usage.