Skip to main content
Agents are saved, versioned runtime configurations tied to one knowledge base. Use these endpoints to manage their lifecycle and run them synchronously or over Server-Sent Events (SSE).
All endpoints on this page are [User+Key]. API keys use agents:read, agents:write, agents:delete, and agents:run scopes as appropriate.

​
Endpoints

MethodPathDescriptionAuth
GET/agentsList agents for a tenant[User+Key]
GET/agents/recent-chatsList recent agent chats[User+Key]
POST/agentsCreate an agent and version 1[User+Key]
GET/agents/:idGet an agent[User+Key]
GET/agents/:id/integrationsCheck connected-app readiness[User+Key]
PATCH/agents/:idUpdate name or status without a new version[User+Key]
POST/agents/:id/deployDeploy a new version[User+Key]
POST/agents/:id/copyCopy or fork an agent[User+Key]
DELETE/agents/:idArchive an agent[User+Key]
POST/agents/:id/schedule/enableEnable its schedule[User+Key]
POST/agents/:id/schedule/disableDisable its schedule[User+Key]
GET/agents/:id/runsList runs[User+Key]
GET/agents/:id/runs/:runIdGet a run[User+Key]
POST/agents/:id/runs/:runId/stopStop a run[User+Key]
POST/agents/:id/messagesRun or continue an agent[User+Key]
POST/agents/:id/messages/streamRun or continue an agent over SSE[User+Key]

​
List agents

GET /agents
​
tenant_id
string
required
Tenant whose agents to list.
curl "$AUTOSAGE_URL/agents?tenant_id=TENANT_ID" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"

​
List recent agent chats

GET /agents/recent-chats
​
tenant_id
string
required
Tenant whose agent chats to list.
​
limit
number
Maximum number to return, from 1 to 50.

​
Create an agent

POST /agents Creation validates the full configuration and publishes version 1.
​
tenant_id
string
required
Tenant that owns the agent.
​
name
string
required
Human-readable agent name.
​
goal
string
required
The outcome the agent should pursue.
​
instructions
string
required
Behavioral and output guidance.
​
model_id
string
required
Supported model identifier.
​
selected_knowledge_base_id
string
required
Knowledge base used for retrieval. This choice is fixed after creation.
​
web_search_enabled
boolean
Allow web search during runs.
​
use_memory_enabled
boolean
Allow durable-memory behavior when tenant and knowledge-base settings permit it.
​
enabled_integration_slugs
string[]
Connected apps the agent may use.
​
enabled_mcp_ids
string[]
IDs of MCP servers already registered for the organization.
​
attached_skills
object[]
Skill attachments, each with skill_id and mode always or auto.
​
callable_agents
object[]
Delegates, each identified by agent_id.
​
custom_tools
object[]
Custom HTTP tool definitions. Secret header values are encrypted and masked when read back.
​
external_subject_id
string
Subject bound to an API-key-created agent for connected apps and durable-memory isolation.
​
schedule
object
Optional schedule draft. Supported modes are manual, daily, weekly, monthly, custom, and cron.
curl -X POST "$AUTOSAGE_URL/agents" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "TENANT_ID",
    "name": "Support specialist",
    "goal": "Resolve support questions from approved documentation.",
    "instructions": "Answer concisely and cite the relevant source.",
    "model_id": "MODEL_ID",
    "selected_knowledge_base_id": "KB_ID",
    "web_search_enabled": false,
    "use_memory_enabled": true
  }'
The knowledge base is immutable after creation. Use the copy endpoint to place equivalent configuration on another knowledge base.
For the complete nested schemas for schedules, tools, skills, and delegates, use /swagger.

​
Get an agent

GET /agents/:id Returns the current agent configuration, schedule, version, and recent run information. Secret custom-tool headers are masked.

​
Check connected-app readiness

GET /agents/:id/integrations Returns the connection status of the apps enabled for the identity that will run the agent, including whether scheduled runs are supported.

​
Update agent metadata

PATCH /agents/:id Updates name or status (active or archived) without creating a new version. 
curl -X PATCH "$AUTOSAGE_URL/agents/AGENT_ID" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support specialist — EMEA" }'

​
Deploy a new version

POST /agents/:id/deploy Accepts the same complete configuration as agent creation. A successful deploy increments the version; a failed validation leaves the previous version unchanged.
In-flight runs stay pinned to the version they started with. New runs use the newly deployed version.

​
Copy an agent

POST /agents/:id/copy
​
name
string
Optional name for the copy.
​
selected_knowledge_base_id
string
Optional destination knowledge base.
The copy is a new agent. Its schedule is copied in a disabled state so it cannot fire unexpectedly.

​
Archive an agent

DELETE /agents/:id Archives the agent and disables its schedule while preserving its run history.

​
Enable or disable a schedule

POST /agents/:id/schedule/enable enables the saved non-manual schedule. POST /agents/:id/schedule/disable pauses it. Neither action creates a new agent version.
Schedules run on cron-style cadences. See Scheduling for UTC behavior and supported recurrence patterns.

​
List and inspect runs

GET /agents/:id/runs returns the agent’s runs. GET /agents/:id/runs/:runId returns one run and verifies that it belongs to the agent in the path. Run status can be queued, running, completed, failed, or cancelled.

​
Stop a run

POST /agents/:id/runs/:runId/stop Stops an in-flight run. Partial output already generated remains available with the run and its chat. Stopping a terminal run returns a conflict response.

​
Send an agent message

POST /agents/:id/messages Starts a run, or continues the run associated with chat_id, and returns a complete JSON response.
​
message
string
required
Message to send to the agent.
​
chat_id
string
Existing agent chat to continue. Omit it to start a new run and chat.
​
model
string
Optional model override for this turn.
​
external_subject_id
string
External end-user subject for API-key calls.
​
skill_ids
string[]
Skills to load for this message.
​
delegate_agent_ids
string[]
Additional delegates available for this message.
curl -X POST "$AUTOSAGE_URL/agents/AGENT_ID/messages" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Summarize the current refund policy." }'
The response includes chat_id, run_id, and run data. Reuse chat_id to continue the same run.

​
Stream an agent message

POST /agents/:id/messages/stream Accepts the same body as the non-streaming endpoint and returns SSE. Response headers include X-Chat-Id and, for a new run, X-Run-Id. 
curl -N -X POST "$AUTOSAGE_URL/agents/AGENT_ID/messages/stream" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Investigate the most common support issue." }'
The stream uses the same runtime events documented in Chat & streaming, including ping, agent_thought, final_response, sources, tokens, done, and error.

​
Next steps

Agent lifecycle

Understand versions, pinned runs, schedules, and terminal states.

Build an agent

Create and invoke an agent end to end.

Agent configuration

Learn how tools, skills, connected apps, and delegates combine.

Chat streaming

Consume runtime events safely.