Agent API reference

Interact with your Fold Agent programmatically using the REST API. All endpoints require a Bearer token (API key or JWT) and are scoped to the authenticated workspace.

Chat (POST /agent/chat)

Send a message to the agent and receive a response. The agent uses its profile, conversation history, memories, and built-in tools to generate a reply.

curl -X POST https://api.fold.run/agent/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What do I have on my calendar today?",
    "session_id": "sess_abc123"
  }'

Field	Type	Required	Description
message	string	Yes	Your message to the agent
session_id	string	No	Continue an existing conversation session
stream	boolean	No	Stream the response via SSE (default false)
model	string	No	Override the default AI model

When stream is true, the response is delivered as server-sent events. Each event contains a chunk of the agent's reply.

Voice (POST /agent/voice)

Upload audio to be transcribed and processed by the agent. Supported formats: wav, mp3, ogg, webm, flac, m4a.

curl -X POST https://api.fold.run/agent/voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "audio=@recording.m4a"

The response includes the transcription and the agent's reply:

{
  "transcript": "What meetings do I have tomorrow?",
  "response": "You have two meetings tomorrow...",
  "session_id": "sess_xyz789"
}

Agent profile (GET/PUT /agent/profile)

Read or update the agent profile that defines your agent's personality.

# Get the current agent profile
curl https://api.fold.run/agent/profile \
  -H "Authorization: Bearer YOUR_API_KEY"

# Update the agent profile
curl -X PUT https://api.fold.run/agent/profile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "## Identity\nI am Aria, your executive assistant.\n\n## Values\n- Concise and professional\n- Proactive about deadlines"
  }'

Key endpoints overview

Method	Endpoint	Description
POST	/agent/chat	Send a message to the agent
POST	/agent/voice	Transcribe audio and chat
GET/PUT	/agent/profile	Read or update the agent profile
GET/POST	/agent/memories	List or create memories
POST	/agent/memories/search	Search memories by text
GET/POST	/agent/notes	List or create notes
GET/POST	/agent/contacts	List or create contacts
GET/POST	/agent/reminders	List or create reminders
GET/POST	/agent/knowledge	List or upload knowledge documents
GET/POST	/agent/routines	List or create routines
GET/POST	/agent/channels	List linked channels
POST	/agent/channels/pair	Generate a channel pairing code
GET	/agent/conversations	List conversation sessions
GET/POST	/agent/emails	List or create email drafts
POST	/agent/emails/:id/send	Send an approved email draft
GET/POST	/agent/webhook-triggers	List or create webhook triggers

All list endpoints support limit and offset query parameters for pagination.