Develop and extend
Concept Available

API Architecture and Request Boundaries

The API image exposes three HTTP composition roots: Product API, Ingest API, and Communications application. Each has its own caller and authentication contract while sharing dependency injection and persistence infrastructure.

For
Backend developers
On this page
  1. Web Chat ownership
  2. Layering
  3. Tenancy and authorization
  4. Transactions and Domain Events
  5. Startup, schema, and tests
  6. Agent Template references
01

Web Chat ownership

The api/domains/web_chat/ domain owns dashboard chat requests, user-scoped thread history, and the authenticated SSE surface. It uses the Communications delivery pipeline and built-in Web Chat Connection. Reads require Agent activity permission; mutations require Agent update permission. This is distinct from external provider webhook authentication and runtime protocol credentials.

  1. 01.1

    See /guides/agents/web-chat for permissions and thread behavior.

02

Layering

The default dependency direction is routes to services to repositories to the shared PostgreSQL delegate, with services also calling external adapters. Routes authenticate, parse, delegate, and return. Services own business rules and error translation. Repositories own SQL and tenant-aware query composition.

  1. 02.1

    The three composition roots are api/api_app.py for the Product API, api/ingest_app.py for Ingest, and api/communications_app.py for Communications.

  2. 02.2

    User-facing Communication Connection management follows the same Product API layering rules. Platform Plugin behavior lives under api/domains/communications/plugins/, while provider HTTP clients and other external mechanisms remain infrastructure concerns. Platform Plugins do not belong in Agent Runtime builders or Product API routes. See /guides/develop/add-platform for the focused Platform Plugin guide.

  3. 02.3

    Product API: /api/v1 on port 8000: authenticated product, Organization, Agent, Connection-management, Template, Skill, activity, and Platform administration routes.

  4. 02.4

    Ingest API: /ingest/v1 on port 8001: Agent Runtime Tool Call and Tool Result telemetry.

  5. 02.5

    Communications application: /communications/v1 on port 8002: Runtime Delivery protocol, Platform Driver callbacks, provider webhooks, supervised ingress, and outbound Delivery.

03

Tenancy and authorization

Organization routes carry the Organization ID and require a real persisted Membership. Platform routes use the Platform Administrator boundary and resolve no active Organization. Agent visibility is applied before count and pagination, while services check the caller’s effective Agent action Permissions. Inaccessible and cross-Organization Agent resources are normally concealed with 404; a visible resource lacking the required action returns 403.

  1. 03.1

    Runtime Ingest, the Runtime Communications protocol, Platform Driver callbacks, and provider webhooks are separate non-user boundaries. They do not use an ordinary user session or receive implicit Organization authority. Provider webhook authentication is provider-specific and delegated to the selected Platform Plugin.

  2. 03.2

    Agent-subordinate Communication Connections use Product API routes such as /api/v1/organizations/{organization_id}/communication-platforms, /api/v1/organizations/{organization_id}/agents/{agent_id}/connections, /api/v1/organizations/{organization_id}/agents/{agent_id}/connections/{connection_id}, and the corresponding summary and journal routes. Connections are subordinate to an Agent, so every query and mutation validates Organization, Agent, and Connection ownership together.

  3. 03.3

    Agent Access governs visibility and ordinary Connection actions. Credential creation, replacement, and retirement also require secret-management authority; Connection credentials are encrypted separately from Agent Secrets and omitted from read responses. Connection identity remains present in diagnostics, directory, journal, reconnect, retry, and Delivery operations.

  4. 03.4

    The Communications application serves non-user routes including /communications/v1/agents/{agent_id}/deliveries/claim, Delivery reply and completion routes, /communications/v1/connections/{connection_id}/events, and /communications/v1/webhooks/{connection_id}. These are not Product API shortcuts: they use Runtime, driver, or provider-specific authentication, and a Runtime reply remains bound to the Delivery, Connection, and Conversation that produced the work.

  5. 03.5

    Skills use three Product API scopes. Platform routes use /api/v1/platform/skills with Platform Administrator authority; Organization routes use /api/v1/organizations/{organization_id}/skills with Membership and Organization Skill Permissions; Agent-private routes use /api/v1/organizations/{organization_id}/agents/{agent_id}/skills with Agent Access Permissions. Agent-private Skills retain both identities, never expose another Agent’s private lineage, and keep list, detail, draft, publish, version, fork, source-update, and deletion within the owning scope. Agents and Templates pin exact immutable Skill Versions.

  6. 03.6

    Product API user request: current authenticated user, scoped Organization Membership and Permission, and Agent Access where applicable.

  7. 03.7

    Platform administration request: Platform Administrator authority with no active Organization.

  8. 03.8

    Runtime Ingest: per-Agent Ingest identity; Tool Call telemetry only, never canonical Conversation Messages.

  9. 03.9

    Runtime Communications protocol: per-Agent Communications bearer identity and the supported protocol-version header.

  10. 03.10

    Platform Driver callback: per-Connection driver identity and the supported driver-version header.

  11. 03.11

    Provider webhook: Connection-scoped authentication delegated to the selected Platform Plugin.

04

Transactions and Domain Events

The shared delegate commits per operation, so several repository calls are not automatically atomic. Workflows requiring all-or-nothing behavior need an explicit transaction. Event-producing repositories commit business state, one Outbox Message, and intended Event Deliveries in one session.

  1. 04.1

    The Communications operation journal is not a Domain Event Outbox or Event Delivery log. Domain Events record selected immutable business facts; the Communications journal records provider ingress, policy, Delivery, retry, reconnect, and failure operations. See /guides/domain-events-and-delivery and /guides/observe-and-govern/communication-diagnostics for the detailed boundaries.

05

Startup, schema, and tests

Product API startup ensures the bootstrap Platform Administrator, publishes missing isolated bundled Skills into the global Platform Skill catalogue, and seeds missing predefined Platform Templates. Existing database-owned Platform resources remain canonical after bootstrap.

  1. 05.1

    Schema changes require Alembic migrations. Integration tests use the real FastAPI app and migrated PostgreSQL with additive dependency overrides.

  2. 05.2

    Communications changes also require focused Platform Plugin, gateway, Connection-isolation, and Runtime protocol coverage. A new Agent-subordinate route must prove Agent Access and cross-Organization concealment. See /guides/testing-and-verification and /guides/develop/testing for coverage selection.

06

Agent Template references

A non-deleted Agent selects exactly one published configuration version, and that selection can reference one of three sources.

  1. 06.1

    The Agent table’s CHECK constraint requires exactly one of these fields to be non-null while deleted_at is null.

  2. 06.2

    Soft-deleted Agents can retain historical pins or be detached when an old shared lineage is purged. The active three-source constraint does not require immediate clearing of all pins on deletion.

  3. 06.3

    An Override draft is not a published version and cannot be used as the Agent’s active selection. Publishing a new version does not automatically move an existing Agent to it. See /guides/templates-versions-and-skills for the authoring and selection model.

  4. 06.4

    platform_template_id: a Platform Template Version.

  5. 06.5

    agent_template_id: an Organization Template Version.

  6. 06.6

    agent_template_override_version_id: a published Agent Template Override Version belonging to that Agent.

Documentation