Developer & Agent API: ucalyptus.me

This is the developer portal for ucalyptus.me, the machine-readable API surface for AI agents and developers. > For agents: the full contract is the OpenAPI 3.1 spec. The plain-language auth flow is in auth.md. Public token-verification keys are at /.well-known/jwks.json.

Quick reference

Authentication quickstart

The API uses OAuth 2.0 client_credentials (RFC 6749 §4.4). It is stateless and anonymous. Any agent can register. There are no user accounts; registration proves a client exists, not who it is. Client secrets are HMAC-derived, never stored. Tokens are ES256 JWTs valid for 15 minutes.

1. Register a client

curl -sX POST https://ucalyptus.me/oauth/register \
  -H 'content-type: application/json' \
  -d '{"client_name":"my-agent"}'
# -> { "client_id": "...", "client_secret": "...", ... }

2. Get a token

curl -sX POST https://ucalyptus.me/oauth/token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET'
# -> { "access_token": "<ES256 JWT>", "token_type": "Bearer", "expires_in": 900, "scope": "read:extended" }

3. Call the gated endpoint

curl -s https://ucalyptus.me/api/agent/full-profile \
  -H 'authorization: Bearer YOUR_ACCESS_TOKEN'
# 200 -> extended CV/availability JSON
# 401 -> { "error": "invalid_token", ... }  (with a WWW-Authenticate header
#          pointing at /.well-known/oauth-protected-resource)

All error responses are JSON with an error and error_description, so agents never have to parse an HTML error page.

Endpoints

WebMCP (browser agents)

Every page on this site registers read-only WebMCP tools via document.modelContext (Chrome 149+ spec, with a navigator.modelContext fallback): get_site_overview, search_content, list_content, get_content_item, get_cv_summary, get_contact_info, get_faq, and the OAuth-gated get_full_profile. Tool descriptors are in /.well-known/mcp.json and /.well-known/agent-card.json.

Questions

Email [email protected] or open a discussion on GitHub.