Skip to main content
The Superagents API is in beta. Its endpoints and responses may change.
The Superagents API lets you talk to a Superagent from your own code or product. Send it messages and read its replies, manage what it remembers about you, and get notified when it answers. Use the Superagents API to:
  • Open your conversation with a Superagent and read its messages.
  • Send the agent a message and get its reply.
  • Delete messages from your conversation.
  • List what the agent remembers about you, and delete your own memories.
  • Subscribe a URL to the agent’s conversation events with webhooks, and send a test delivery.

​
Prerequisites

  • A personal access token that can reach the agent. See Authentication to get one.
  • Access to the agent. Managing its webhooks needs editor access to the agent.
Webhooks need the Builder plan or higher. See Adding a webhook.

​
Superagent ID

Every endpoint includes the agent’s ID in the URL path as agent_id. To get your Superagent ID:
  1. Open your Superagent.
  2. Click the agent name at the top of the editor, then click View all agents.
  3. Click the More actions icon on the Superagent card.
  4. Click Copy Superagent ID.

​
Conversations

You have one main conversation with each Superagent. Create Superagent conversation returns it, creating it the first time you call it, so calling it again returns the same conversation. If you own the agent, it’s the conversation you chat in inside Base44. Send Superagent message keeps the request open while the agent works, including any tools it runs, and returns its final reply. A reply that needs many tool calls can take minutes, so set a generous client timeout. Each reply uses credits from the agent’s workspace.

​
Memories

A Superagent saves memories as it learns things worth keeping. A global memory applies to everyone who uses the agent, and a user memory applies only to you. You can list both, but you can delete only your own user memories.

​
Webhooks

A webhook sends a request to your URL when one of these events happens:
  • message.created: A message is added to a conversation.
  • message.completed: The agent finishes a reply.
An agent can have up to 5 webhooks, and each target URL has to be a public HTTPS URL. Base44 sends each event once and doesn’t retry a failed delivery. To check that a request came from Base44, set generate_secret to true when you create the webhook, so deliveries are signed.

​
Rate limits

Each endpoint allows 100 requests per minute, except Send Superagent message, which allows 20. If you exceed a limit, you get a 429 Too Many Requests response. Wait before retrying.