API conventions & area guide

Use this page to choose an area of the HTTP API. Its links lead to operation tables, schemas and examples generated from the repository's OpenAPI contract. Those describe this checkout; an older running server may expose fewer operations. The sections below explain when to use each area.

For a default local server, requests use http://127.0.0.1:18880/api/v2. API errors use this envelope:

{"error":{"code":"traverser_not_found","message":"unknown traverser"},"request_id":"c9ec0e4b-08a4-44d6-aff0-4f46eb76889f"}

Send the ATFGraph key in X-API-Key. If a platform proxy also requires authentication, its credential goes in Authorization. Roles include admin, invoke and worker; administrators have the other permissions. A loopback server with no configured tokens permits development access without a key. Include the response's request_id when reporting a failure.

Starting and reading work

Traversers

Submit work to label.capability, read its result or path, list runs with filters and pagination, cancel work, or restart a run. Most calling applications begin here. See Start a traverser.

Events

Read a traverser's stored events or follow its live event stream. Use this for progress displays and reconnectable monitoring, as the Console does.

Sessions

Create a session and pass its ID to related runs. This gives a conversation a shared session-memory scope. atfg traverse --new-session creates one for you; the application chooses when to reuse it.

Approvals

List approval requests and record a human's decision. A handler requests the approval, and the server holds its traverser in waiting until it can resume.

What is registered

Discovery

Inspect server information, registered nodes and their capabilities. Under /api/v2/ard, manage publications and search what has been exposed for discovery. Registration and publication are separate steps; atfg ls reads registered capabilities.

Admin

Register a versioned node definition. A normal worker does this during startup. A registered definition cannot be changed under the same version.

Worker

Workers use these operations to enroll, claim tasks, renew leases, report progress, complete tasks and drain. The Python worker implements this protocol for you; use it directly when implementing another worker. Operators use GET /api/v2/workers to inspect the fleet. See Monitor over HTTP.

State a traverser can use

Memory

Store scoped key/value state under global, session, actor or workflow. Revisions support compare-and-set writes; the change feed lets callers follow updates. Your application chooses keys, values and retention.

Knowledge

Store documents, let the server chunk them, and search with lexical BM25 scores and citations. For semantic or hybrid retrieval, the SDK combines document knowledge with embeddings and memory vectors; your team configures the embedding provider.

Checkpoints

Save and read named, revisioned checkpoints during execution. On retry or approval resume, the handler starts again and uses these values to reuse prior work.

Artifacts

Upload, list, download and delete files associated with a traverser. Use artifact references when output should point to stored bytes.

Operating the server

Observability

Read stored usage, node logs and run metadata, and manage the outbound observability webhook. Operators can also read server counts at /api/v2/stats and model circuit state at /api/v2/model-health. These services are accessible over HTTP, beyond the Console.

RuntimeSettings

Read and update namespace settings documents. Saving a setting and applying it to the process are separate operations; use the apply operation when the change must take effect.

Emitters

Configure schedules and inbound event sources that start traversers. Application teams choose target capabilities, event filters and input transformations. Delivery logs and replay help investigate failed events.

Retention

Preview which old traversers, events and logs a retention rule would remove, then apply it. Review the preview before pruning.

Health

Probe unauthenticated liveness at GET /health. A healthy process does not by itself prove that a worker or downstream provider is ready.

Identity and access

Access

Manage access policies and connector grants. These control which traversals a caller can start and which configured connector access is permitted.

Credentials

Enroll node identities, issue and verify credentials, revoke them, and manage the tag ledger. The server retains signing keys rather than handing them to workers.

Identity

Create node signing identities, sign recorded paths and verify their proofs. A valid signature establishes integrity and signer identity under the selected trust rules; it does not establish that an answer is correct.

Also generated

• Schemas: every component schema with field tables and examples.
• Feature areas: what each area covers and which roles it needs.
• Examples: the example directories and the capabilities they declare.
• CLI reference: every atfg command and flag, generated from the binary.