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 $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event":"demo.created","payload":{"user":"friend-demo","value":123}}'

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