Agent API overview

The Agent API lets an agent manage itself at runtime: its identity, memory, integrations, files, scheduled jobs, and more. Each call uses the agent’s own API key, so an agent can only ever act as itself.

Install 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 each route's path
});

Create one client and reuse it. Every method lives directly on the client.

Authentication

Every request sends the agent’s API key as a bearer token:

Authorization: Bearer <agent-api-key>

Alfe resolves the agent’s identity, its agentId and the tenantId it belongs to, from that token. You never pass those ids yourself. See Authentication for how an agent gets its key.

Reference by capability

Area	What it covers
Authentication	The bearer-token model and how an agent gets its key.
Identity	whoami, resolving who you’re talking to, and managing identities.
Memory	Store, search, learn from, and inspect the agent’s persistent memory.
Integrations	List, install, configure, and remove integrations, and drive OAuth connect flows.
Connected accounts	Read credentials for accounts the agent can use.
Workspace sync	Back up and restore the agent’s workspace files and sessions.
Shared knowledge	Search org, team, and project knowledge, and propose changes.
Secrets	Per-scope encrypted secret storage with client-side encryption.
Jobs	Schedule the agent’s own future turns and read their run history.
Remote sessions	Ask a person to take over the agent’s live browser.
GPU instances	Rent, inspect, and destroy GPU machines with your connected Vast.ai key.
Webhooks	Create and manage the agent’s own inbound webhooks.
Search and news	Web, image, and news search, plus news headlines.
Image generation	Generate an image from a text prompt.
Text-to-speech and speech-to-text	One-shot audio generation and transcription.
Your agent’s profile	Change the agent’s own name, voice, and avatar.
Chat	Open a direct conversation and upload attachments.
Phone and messaging	Manage a phone number and send SMS, WhatsApp, and calls.

Representative calls

Here’s the shape of the API.

examples.ts

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

// Search and store memory.
const { memories } = 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 everything effective for this agent.
const { integrations } = await client.listIntegrations();
// GET /agent/integrations

// Schedule a check in the morning.
const job = await client.createJob({
  name: "Morning check",
  prompt: "Summarise anything that needs a reply today.",
  schedule: { kind: "cron", expr: "0 7 * * 1-5" },
  timezone: "Australia/Sydney",
});
// POST /agent/jobs

Responses

Every successful JSON response wraps its payload in a top-level data field. The client unwraps it 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": "…" } }

Errors and retries

A non-2xx response throws an error with the HTTP status and, when the server sends one, a machine-readable code. Branch on those, never on the message text.

try {
  await client.runJobNow(jobId);
} catch (error) {
  const { status, code } = error as { status?: number; code?: string };
  if (code === "rate_limited") {
    // wait a minute, then try again
  }
}

The client retries a safe read once after a transient failure. It doesn’t retry changes, unless a method is documented as safe to repeat.

Call the API directly

The client is a thin wrapper over plain HTTPS, so you can call the same endpoints from any language with the Authorization: Bearer header. Most routes live under /agent/ on the API host. The voice and phone routes live under /voice/ and /mobile/.

Next steps

• Follow a tutorial end to end.
• For self-onboarding and platform management over MCP instead of HTTP, see MCP on Alfe.