APIs, Hooks und Friend-Keys verständlich dokumentiert.

Health Check

Simple uptime check for monitors, Traefik, and humans. Does not require an API key.

{
  "ok": true,
  "service": "agent-api-hub",
  "time": "2026-05-23T21:00:00+00:00"
}

curl https://docs.pau1.cloud/health

Who am I?

Returns the current API key identity, granted scopes, and rate limit.

{
  "key_id": "key_abc123",
  "owner": "friend-demo",
  "scopes": [
    "agent:brief",
    "tools:summarize"
  ],
  "limits": {
    "rate_limit_per_minute": 30
  }
}

curl -H "Authorization: Bearer $TOKEN" https://docs.pau1.cloud/v1/me

Visible Services

Lists only the services that the current key is allowed to call.

{
  "services": [
    {
      "id": "agent.brief",
      "name": "Agent Brief",
      "required_scope": "agent:brief",
      "method": "POST",
      "path": "/v1/agent/brief"
    }
  ]
}

curl -H "X-API-Key: $TOKEN" https://docs.pau1.cloud/v1/services

Agent Echo

Returns the submitted message and metadata unchanged. Useful for testing auth, JSON shape, and client plumbing.

{
  "message": "Hello Paul",
  "metadata": {
    "source": "demo-client"
  }
}

{
  "message": "Hello Paul",
  "metadata": {
    "source": "demo-client"
  },
  "echoed_at": "2026-05-23T21:00:00+00:00"
}

curl -X POST https://docs.pau1.cloud/v1/agent/echo \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello Paul","metadata":{"source":"demo-client"}}'

Agent Brief

Creates a deterministic brief from supplied text: compact summary, bullets, and word count.

{
  "title": "Meeting notes",
  "text": "Long text goes here...",
  "bullets": 5
}

{
  "title": "Meeting notes",
  "summary": "Compact summary...",
  "bullets": [
    "Key point one",
    "Key point two"
  ],
  "word_count": 420
}

curl -X POST https://docs.pau1.cloud/v1/agent/brief \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Meeting notes","text":"FastAPI exposes scoped APIs. Friend keys only get selected services.","bullets":3}'

Extractive Summarizer

Ranks sentences by keyword frequency and returns the strongest sentences as a summary.

{
  "text": "Sentence one. Sentence two. Sentence three.",
  "sentences": 3
}

{
  "summary": "Sentence one. Sentence three.",
  "selected_sentences": [
    "Sentence one.",
    "Sentence three."
  ],
  "sentence_count": 2
}

curl -X POST https://docs.pau1.cloud/v1/tools/summarize \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"APIs need docs. Docs need examples. Examples reduce support.","sentences":2}'

Webhook Test Receiver

Receives a named event with arbitrary JSON payload and returns a timestamped receipt.

{
  "event": "demo.created",
  "payload": {
    "user": "friend-demo",
    "value": 123
  }
}

{
  "ok": true,
  "event": "demo.created",
  "payload": {
    "user": "friend-demo",
    "value": 123
  },
  "received_at": "2026-05-23T21:00:00+00:00"
}

curl -X POST https://docs.pau1.cloud/v1/webhook/test \
  -H "Authorization: Bearer *** \
  -H "Content-Type: application/json" \
  -d '{"event":"demo.created","payload":{"user":"friend-demo","value":123}}'

ElevenLabs Conversation Initiation

Returns ElevenLabs conversation-initiation client data for inbound phone calls.

{
  "caller_id": "+491234",
  "called_number": "+4989123",
  "call_sid": "CA123"
}

{
  "type": "conversation_initiation_client_data",
  "dynamic_variables": {
    "caller_id": "+491234",
    "call_sid": "CA123"
  }
}

curl -X POST https://docs.pau1.cloud/v1/voice/elevenlabs/initiation -H "X-ElevenLabs-Webhook-Secret: ***" -H "Content-Type: application/json" -d '{"caller_id":"+491234","call_sid":"CA123"}'

Hermes Phone Command Bridge

Starts a Hermes /v1/runs task from an ElevenLabs server tool and returns run status/output.

{
  "command": "Check the server health",
  "caller_id": "+491234",
  "call_sid": "CA123",
  "wait_seconds": 45
}

{
  "ok": true,
  "status": "completed",
  "run_id": "run_abc",
  "session_id": "elevenlabs:CA123",
  "output": "Done",
  "message": "Hermes finished."
}

curl -X POST https://docs.pau1.cloud/v1/voice/hermes-command -H "X-API-Key: $TOKEN" -H "Content-Type: application/json" -d '{"command":"Check the server health","wait_seconds":10}'

ElevenLabs Phone Integration

Returns token-safe setup payloads for wiring ElevenLabs phone calls to Hermes.

{
  "service_name": "tom-elevenlabs-phone-hermes",
  "hermes_tool_url": "https://docs.pau1.cloud/v1/voice/hermes-command"
}

curl -H "X-API-Key: $TOKEN" https://docs.pau1.cloud/v1/integrations/elevenlabs-phone

Parlant OpenAPI Connector

Returns the exact OpenAPI service payload needed to register this API Hub as a Parlant tool service.

{
  "service_name": "paul-api-hub",
  "parlant_update_service_payload": {
    "kind": "openapi",
    "openapi": {
      "url": "https://docs.pau1.cloud",
      "source": "https://docs.pau1.cloud/openapi.json"
    }
  }
}

curl -H "Authorization: Bearer *** https://docs.pau1.cloud/v1/integrations/parlant

Supertonic OpenAPI Connector

Returns token-safe OpenAPI connection details for registering this API Hub with Supertonic.

{
  "service_name": "paul-api-hub",
  "kind": "openapi",
  "supertonic_integration_payload": {
    "kind": "openapi",
    "openapi": {
      "url": "https://docs.pau1.cloud",
      "source": "https://docs.pau1.cloud/openapi.json"
    },
    "auth": {
      "type": "api_key",
      "headers": {
        "Authorization": "Bearer ***",
        "X-API-Key": "***"
      }
    },
    "voice_policy": {
      "default_voice": "F4",
      "fallback_voices": [],
      "note": "No Edge fallback or substitute voices."
    },
    "runtime": {
      "preferred_server": "local loopback supertonic serve",
      "health_path": "/health",
      "speech_path": "/v1/text-to-speech"
    }
  }
}

curl -H "Authorization: Bearer ***" https://docs.pau1.cloud/v1/integrations/supertonic

List API Keys

Returns metadata for all known keys: owner, scopes, creation time, revocation state, rate limit, and fingerprint.

[
  {
    "id": "key_abc123",
    "owner": "Paul Admin",
    "scopes": [
      "admin:keys",
      "agent:brief"
    ],
    "revoked_at": null,
    "rate_limit_per_minute": 300,
    "fingerprint": "sha256:abcd1234"
  }
]

curl -H "Authorization: Bearer $ADMIN_TOKEN" https://docs.pau1.cloud/v1/admin/keys

Create Scoped API Key

Creates a new scoped key for a friend, customer, service, or integration. Raw token is returned once.

{
  "owner": "friend@example",
  "scopes": [
    "agent:brief",
    "tools:summarize"
  ],
  "note": "limited friend key",
  "rate_limit_per_minute": 30
}

{
  "token": "bah_live_generated_once",
  "key": {
    "id": "key_abc123",
    "owner": "friend@example",
    "scopes": [
      "agent:brief",
      "tools:summarize"
    ],
    "fingerprint": "sha256:abcd1234"
  }
}

curl -X POST https://docs.pau1.cloud/v1/admin/keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"owner":"friend@example","scopes":["agent:brief","tools:summarize"],"note":"limited friend key","rate_limit_per_minute":30}'

Revoke API Key

Revokes a key by ID. Revoked keys can no longer authenticate.

{
  "id": "key_abc123",
  "revoked": true,
  "revoked_at": "2026-05-23T21:00:00+00:00"
}

curl -X DELETE -H "Authorization: Bearer $ADMIN_TOKEN" https://docs.pau1.cloud/v1/admin/keys/key_abc123