Agent API overview

Agents have a self-service API for the things they need at runtime: their own identity, persistent memory, workspace sync, integrations, and more. Endpoints live under the /agent/ path and are authenticated with the agent’s own API key.

The client

The easiest way to call the API is the official client, @alfe.ai/agent-api-client:

npm

npm i @alfe.ai/agent-api-client

pnpm

pnpm add @alfe.ai/agent-api-client

yarn

yarn add @alfe.ai/agent-api-client

agent.ts

import { AgentApiClient } from "@alfe.ai/agent-api-client";

const client = new AgentApiClient({
  apiKey: process.env.ALFE_API_KEY!, // the agent's API key
  apiUrl: "https://api.alfe.ai",     // base host; the client adds the /agent/ prefix
});

Authentication

Every request is authenticated with the agent’s API key as a bearer token:

Authorization: Bearer <agent-api-key>

The agent’s identity — its agentId and the tenantId it belongs to — is resolved on the server from the token. You never pass those ids in the request yourself, which means an agent can only ever act as itself.

Representative endpoints

The API surface is broad; here are a few representative calls to show the shape.

Identity (whoami)

Returns the calling agent’s own identity context.

whoami.ts

const { agentId, tenantId } = await client.whoami();
// GET /agent/identity/whoami

Search and store memory

Query the agent’s persistent memory, or write a new fact to it.

memory.ts

const results = await client.memorySearch("what did we decide about pricing?");
// POST /agent/memory/search

const { memoryId } = await client.memoryStore("Customer prefers email over calls.");
// POST /agent/memory/store

List integrations

See what’s installed for the agent.

const integrations = await client.listIntegrations();
// GET /agent/integrations

Register for workspace sync

Register the agent for cloud workspace backup and sync.

await client.syncRegister({ displayName: "My Agent" });
// POST /agent/sync/register

Reference by capability

The client’s surface is grouped into these reference pages:

Area	What it covers
Authentication	The bearer-token model, the /agent/ prefix, and how an agent gets its key.
Identity	whoami, resolving who you’re talking to, and identity management.
Memory	Store, search, learn, navigate, and inspect the agent’s persistent memory.
Integrations	List, install, configure, and remove integrations; drive OAuth connect flows.
Connected accounts	Read credentials for accounts the agent has connected (GitHub, Google, Xero, and more).
Workspace sync	Back up and restore the agent’s workspace files and sessions.
Shared knowledge	Search and edit org / team / project knowledge the agent is a member of.
Secrets	Per-scope encrypted secret storage with client-side encryption.

A few more endpoints round out the surface and are exposed as client methods: web / image / news search (searchWeb, searchImages, searchNews), chat attachment presigning (presignAttachments), activity recording (recordActivity), and per-agent database access (registerDatabaseCredentials, reportDatabaseAudit).

Response envelope

Every successful response wraps its payload in a top-level data field. The client unwraps it for you and returns the inner value, so await client.whoami() resolves to { agentId, tenantId } directly. When you call the API without the client, read the data field yourself:

{ "data": { "agentId": "agt_…", "tenantId": "…" } }

Beyond the client

The client is a thin wrapper over plain HTTPS requests under /agent/ on the Alfe API host, so you can call the same endpoints directly from any language — send the Authorization: Bearer header. Ready to build something? Follow a tutorial end to end. For self-onboarding and platform management over MCP instead of HTTP, see MCP on Alfe.