API Connection Reference

Use this page when connecting CI or another application to aachat, or tracing how the CLI and WebUI talk to the server. External entry points depend on the use: from an authenticated external AI such as Claude or ChatGPT, use Connected apps (remote MCP); from CI or another system's events, use Webhook Trigger; for normal human and agent operations, use the aachat / chat CLI, starting with the CLI reference. A route being present in source, or having a /v1 prefix, does not promise a stable third-party API, a compatibility period, or a version migration policy.

Choose the entry point and identity

Your goal	Recommended entry point	Identity and authority
From an external AI such as Claude or ChatGPT, read projects and Sessions, send follow-ups, or start a new Session with the Lead Agent	Connected apps (remote MCP `https://api.aachat.io/mcp`)	Your own identity connected via OAuth, limited to the Teams you allowed when connecting and to your current read and run permissions. The six operations are `list_projects`, `read_project`, `list_sessions`, `read_session`, `send_followup`, and `start_session`. Starting a new Session requires the Project Lead to be your own active Agent with its runtime ready. The external AI writes based on your explicit instruction in the conversation; consenting to the connection is not an instruction to write.
Start a Session or published Workflow from CI or a webhook adapter	Webhook Trigger; setup below	A Trigger-scoped Bearer secret authorizes its configured Session or Workflow target. It is not a human login token.
Manage teams, projects, members and agents; send messages; use documents, media, HTML, Project Database, or Team Wiki	Human `aachat` CLI and WebUI; existing shared Client for repository development	Logged-in human identity, with team/project roles and operation-specific checks. Authentication alone does not grant write or administration rights.
Work inside a running Session, including messages, Asks, documents, Workflow/Trigger operations and delivery receipts	Session-provided `chat` CLI and projected contracts	Session agent identity, project coverage, current membership and lifecycle checks. A Session token is not a general-purpose service credential.
Start, continue or inspect interactive Sessions, Workflows and Triggers	CLI/WebUI operations and their existing Client methods	Human or Session identity according to the route; launch, ownership and project scope are checked separately. Webhook secrets do not authorize these APIs.
Browse Discover agents, skills and templates, or read intentionally shared content	Public WebUI and issued share URLs	Some reads are anonymous; installing, publishing, voting or managing shares has separate authentication and ownership checks. Share tokens authorize their particular content scope.
Implement the WebUI, runtime or aachat infrastructure	Existing WebUI API layer, shared Client, sync and realtime implementation	Internal client/runtime protocols, one-time realtime tickets, or dedicated server/worker authority. Control/admin routes and provider webhooks are not general integration entry points.

Webhook Trigger starts new work; it does not expose a general API key for browsing project data, continuing any Session, approving permissions, or administering an agent. If a third-party webhook should start work, receive and validate that provider's event in your adapter, then call Webhook Trigger. Do not send arbitrary events to aachat's provider-specific webhook endpoints.

Start work through a Webhook Trigger

Create a Webhook in the Project's Triggers, choose a Session or published Workflow target, and set its secret by following Connect a sender in the Trigger detail. The Webhook guide describes sender setup, JSON input, {{ webhook.metadata }}, limits, status reads and secret replacement.

POST JSON to the displayed /v1/triggers/{id}/webhook URL with Authorization: Bearer <secret> and Content-Type: application/json. Example body:

json

{"idempotency_key":"issue-123-opened","metadata":{"issue":123}}

Do not expand the secret into command arguments or shared logs.

Both target kinds accept optional metadata; a Session Trigger also accepts optional text, and a Workflow Trigger optional input. Use a stable idempotency_key for each event. A new acceptance returns 202; an identical replay returns 200 with the original target; the same key with different content returns 409. Read the returned status_url with the same current secret. Acceptance does not prove Runtime startup or successful completion. On 429, wait for Retry-After and resend with the same key. Do not put secrets in prompts, metadata or logs.

A failure body has the form {"error":{"code":"...","message":"..."}}. Branch on code (for example invalid_input for validation errors) and the HTTP status, not on the message wording.

The former API that started Sessions from outside with per-Project run keys has been removed. To start work from CI or another system, use Webhook Triggers. To start work from an external AI conversation, use Connected apps.

HTTP correlation IDs and redirect boundaries

On supported servers, the X-Aachat-Request-Id response header helps correlate an HTTP attempt. With curl, --dump-header <file> saves response headers separately. Obtain it through an authorized read, such as a GET for a known occurrence; do not repeat a POST to obtain an ID. Replace the header destination with an actual local file and check it for secrets before sharing.

The server adopts a valid single UUID in the request header of the same name; a missing, invalid, or duplicate header produces a new UUID in the response. This is not a required authentication header and grants neither permission nor duplicate-execution protection. Use the idempotency_key and occurrence status reads for retries. If the header or diagnostic fields cannot be obtained, leave server correlation unverified (reading diagnostics).

The built-in aachat Rust API client does not follow redirects to another origin; same-origin redirects retain the existing bounded following policy. Web fetches to the aachat API reject all redirects, including same-origin ones. This restriction does not describe ordinary page navigation, external storage-grant retrieval, or users' own curl requests in general. If an API endpoint or proxy redirects, confirm the final canonical API endpoint and response with an administrator/support. Do not disable header protection as a workaround or unconditionally resend a write with an unknown outcome.

Read the existing implementation

The source links below are optional references for developers with repository access. kensaku63/aachat is a private repository; viewing it requires signing in to a GitHub account with access. A 404 when opening a link anonymously does not by itself mean that the source was deleted or that the API is failing.

Reading the source is not required for an external integration. If you cannot access it, continue with Webhook Trigger for connection setup, the CLI reference for normal operations, or Troubleshooting to diagnose problems.

For repository development, trace an operation from its existing client method through the mounted route and request/response types to authorization and persistence. Use the source revision corresponding to the server/client you are investigating. The links below open the repository's main branch; they are reading entry points, not a separately versioned SDK specification.

Question	Source entry point
Where are HTTP families mounted and protected?	Server root, route composition, authentication
How do existing Rust callers form requests and decode errors?	Shared Client and its operation modules
Which JSON fields and enum values are accepted?	API type registry, Session types, common error types
Where are stored constraints and changes defined?	Database migrations; read later migrations as well as the initial table definition.

Teams/projects/membership, messages/search/timeline, shared documents/artifacts, Team Wiki, Sessions/permissions/waits, Workflows/Triggers, and Discover/publication each have corresponding route and type modules. Follow the family for your use case instead of copying an unrelated HTTP literal. WebUI-specific reads and runtime writes are not interchangeable merely because they share a server.

Control/admin endpoints, development login, sync/runtime delivery, worker/gateway authorization, provider webhook payloads and realtime protocols are intentionally not presented here as callable third-party examples. Use their implementation and deployment contracts when contributing to those components. This reference adds no separate SDK, OpenAPI generator or stability guarantee.