API Reference

The Rules

One endpoint. One question. "Can I bother my human right now?"

⚡ Quick Start (5 minutes)

Make a request to check availability

Respect the response. If available: false, back off.

curl https://agentz.fyi/api/v1/check \
  -H "Authorization: Bearer az_your_api_key"

Example Response

{
  "available": true,
  "state": "available",
  "suggested_channel": "sync",
  "confidence": 0.85
}

Authentication

Every request needs your API key in the Authorization header.

Authorization: Bearer az_your_api_key_here

Get your key from the Dashboard. Keep it secret.

Base URL

https://agentz.fyi/api/v1

Endpoints

GET

/check

Check if your human is available

Response Fields

Field	Type	Description
available	boolean	Can you interrupt? `true` = yes, `false` = no
state	string	`available` `busy` `meeting` `focus` `dnd`
suggested_channel	string	`sync` (real-time OK) `async` (queue it) `urgent` (emergencies only)
confidence	number	0-1 confidence score (higher = more certain)
try_again	string?	ISO 8601 timestamp of when to retry (if unavailable)

Rate Limits

Plan	Monthly Limit
Free	2,000 requests
Pro ($9/mo)	Unlimited

Error Codes

Status	Code	Meaning
401	INVALID_KEY	Missing or invalid API key
429	RATE_LIMITED	Too many requests, slow down
500	SERVER_ERROR	Something broke on our end

Agent Integration Pattern

Add availability checks to your agent's heartbeat or before any proactive outreach.

Recommended Pattern

Check before you interrupt

# In your agent's decision loop:

async def should_notify_user(message: str, urgency: str = "medium"):
    status = await check_availability()
    
    if status["available"]:
        return True  # Go ahead
    
    if urgency == "critical" and status["suggested_channel"] == "urgent":
        return True  # Emergency override
    
    # Queue for later
    schedule_for(status.get("try_again"))
    return False

🔌 Automation Integrations

Push state updates from any automation platform using our webhook endpoint.

⚡

Zapier

5000+ app integrations

Connect Google Calendar, Slack, Zoom, and more to update your availability automatically.

🔮

Make

Visual automation platform

Build powerful scenarios with Make's visual builder. Great for complex workflows.

Webhook Endpoint

POST https://agentz.fyi/api/v1/webhook/wh_your_token

{
  "state": "busy",
  "reason": "In a meeting",
  "until": "2026-02-08T10:00:00Z",
  "source": "zapier"
}

Get your webhook token from Dashboard → Webhooks

SDKs

Official SDKs coming soon. For now, it's one HTTP call—easy to integrate anywhere.

Python SDK — soonNode.js SDK — soon