Application API
Agent
Clear API and contract surface for Agent, grouped under the application instead of split across generic reference sections.
Documentation Map
Authority
Service IDs:
srv_luiWkJLNbOMG Repos:
Hosts:
https://agent.topolo.app https://topolo-agent.pages.dev https://agent.stg.topolo.us https://agent-api.stg.topolo.us https://topolo-agent-staging.pages.dev https://topolo-agent-stg.topolo-staging.workers.dev Dependencies: topolo-auth, applications-packages, topolo-developers, topolo-p2p, topolo-nexus, topolo-voice
Depends on Topolo Auth: yes
Contract Source
Type: curated
Source: PlatformApplications/TopoloDocs/src/content/public/applications/agent.mdx
Source exists: no
Canonical Agent coverage now lives in the docs application. The backend worker now requires Topolo Auth validation for operator bearer tokens and no longer carries an Agent-local HS256/JWT secret verification path. Browser preboot, shared browser auth, backend Auth validation, widget output, seed validation, and downstream connector headers resolve concrete service ids from Auth service slugs such as `topolo-agent` at runtime instead of carrying concrete service ids in source, Worker vars, build commands, or browser assets. The production Pages `/login` entry renders the shared branded first-party login surface and submits email/password credentials to Auth through the shared client; OAuth and other brokered flows still use hosted Auth. The connector catalog uses the Developers-owned mobile app catalog connector for Android and iOS artifact metadata. Agent exposes `GET /api/widget` for TopoloOne live workspace with active-flow, pending-task, pending-approval, and run-today stats. Agent also exposes `POST /api/public/chat` for the public Lois website-chat assistant embedded by TopoloOne; that route owns persona selection, Turnstile-backed session clearance, source links, rate limiting, and action/deeplink metadata. Agent owns authenticated `/api/person-profiles` routes backed by `person_profiles`, `person_profile_sources`, and `person_profile_style_snapshots` so products can reuse source-backed writing style, speaking style, persona rules, usage policies, authorization evidence references, and Voice profile links without turning every profile into an executable agent. The browser workspace now includes a standalone Person Profiles surface for profile editing, source capture, style reads, and draft preview generation, and the backend exposes `POST /api/person-profiles/:id/preview` for authenticated source-backed previews. Person-profile access is restricted to the subject user and organization admins, not normal peer users. Cross-organization agent actions must enter through TopoloP2P and wait for the P2P policy decision before execution. Staging runs in the separate Topolo Staging Cloudflare account with staging Auth, Nexus, D1, R2, Queue, and Vectorize bindings, and browser/backend fallback URLs resolve to the staging custom domains before production.
API key scopes in Auth catalog: 11
Auth Requirements
No global OpenAPI security scheme is declared.
-
agents.read -
agents.write -
approvals.write -
knowledge.read -
knowledge.write -
reports.read -
runs.invoke -
workflows.read -
workflows.write -
workspace.read -
workspace.write
Runtime and Deployment
Wrangler surfaces: none detected
Environment variables: none derived
Routes: workers.dev or Pages-only delivery
Observability enabled: no explicit signal found
Runtime Surface
Wrangler surfaces: No wrangler file detected in scanned surface
This application does not yet have a source-controlled OpenAPI spec in the docs platform. The current API page is derived from the registered contract source and repository surface.
Failure modes
- No wrangler.toml surface was discovered under the registered repo paths.
- The registered contract source is missing: PlatformApplications/TopoloDocs/src/content/public/applications/agent.mdx
- Neither OpenAPI nor README-derived interface detail was found.