Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zenzap.co/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint allows an external AI agent to bootstrap a complete Zenzap workspace in one request: create the organization, install a bot (the agent itself), and send an invite to the human user.
Rate limit: 1 request per minute per IP. No authentication required.

​
Endpoint

POST https://api.zenzap.co/v2/agentic/organization/create

​
Request

The endpoint supports two content types depending on whether you want to include a company logo. 
{
  "companyName": "Acme Corp",
  "humanEmail": "founder@acme.com",
  "companySize": 50,
  "industry": "Software",
  "botName": "Acme Assistant"
}
For multipart requests, send two parts:
PartTypeDescription
filePartfile (image)Company logo. Max 5 MB. Optional.
metadataapplication/jsonJSON object with the fields below.

​
Request Fields

All fields are required.
FieldTypeConstraintsDescription
companyNamestringMax 100 charactersDisplay name of the organization.
humanEmailstringValid email addressThe human user who will receive an invite and become the org’s first member.
companySizeintPositive integer (> 0)Number of employees. Mapped to a size range.
industrystringNon-emptyFree-text industry description (e.g. “Software”, “Healthcare”).
botNamestringNon-emptyDisplay name for the agent bot installed in the organization.

​
Response

Status: 201 Created 
{
  "organizationId": "067d0b2f-1ee8-49f2-bb09-e2d964c8cf6b",
  "botProfileId": "b@f951b968-bf80-4ee6-bbbe-6ca338f57fc6",
  "channelId": "1b383aef-15c2-44e2-b599-d1d40a8b286c",
  "humanProfileId": "a3c2e1d0-9f8b-4e7a-b6c5-d4e3f2a1b0c9",
  "credentials": [
    { "label": "API Key", "value": "utxDAedgfFXglaLX" },
    { "label": "API Secret", "value": "66AybzV7s0afLeKKqpxC7wLKCTk5d7bT" },
    { "label": "Control Topic ID", "value": "1b383aef-15c2-44e2-b599-d1d40a8b286c" }
  ]
}
FieldDescription
organizationIdUUID of the newly created organization.
botProfileIdThe bot’s identity (format: b@<uuid>). Use as senderId filter when polling.
channelIdThe bot’s control channel (same as Control Topic ID credential).
humanProfileIdThe pending profile ID of the invited human. Use this to identify the human once they join.
credentialsAPI Key (for Bearer auth), API Secret (for request signing — store securely), and Control Topic ID.

​
Error Codes

StatusBodyCause
400companyName is requiredMissing or empty companyName.
400companyName exceeds max lengthcompanyName longer than 100 characters.
400invalid humanEmailhumanEmail is not a valid email address.
400companySize must be a positive integercompanySize is 0 or negative.
400industry is requiredMissing or empty industry.
400botName is requiredMissing or empty botName.
400Unable to create organizationGeneric conflict error (e.g. email or domain already in use).
429(empty)Rate limit exceeded (1 req/min per IP).

​
Instructions for AI Agents

This section is written for AI agents. If you’re a human developer, see Build Your Own Agent for a full integration walkthrough.
All Zenzap API requests must use https://. Never use plain http:// — requests over HTTP will be rejected.

​
OpenClaw-Based Agents — Plugin Setup

If you are an OpenClaw-based agent, ask your human to install the Zenzap plugin before you proceed with anything else: 
openclaw plugins install @zenzap-co/openclaw-plugin
Once the human confirms the plugin is installed, continue with the steps below. After you receive the 201 response from the create-organization call, you will use the returned credentials to configure the plugin — see the “OpenClaw agents: Configure the plugin” step in the post-response workflow.

​
Before Calling the API — Collect from the Human

Always ask the human these 4 questions before making the request. Do not assume or infer the answers:
  1. Company name — What’s the name of your company or workspace?
  2. Your name in Zenzap (bot name) — What should I be called inside your workspace? (This is how I’ll appear to your team.)
  3. Industry — What industry are you in? (e.g. Software, Healthcare, Finance — used for statistical purposes only.)
  4. Company size — How many employees does your company have? (Used for statistical purposes only.)

​
After the 201 Response — What to Do Next

Once you receive the 201 response, you have a live bot with credentials. Follow these steps in order:

​
OpenClaw agents: Configure the plugin

Skip this step if you are not an OpenClaw-based agent.
Build a connection token from three values in the credentials array of the 201 response: Control Topic ID, API Key, and API Secret. Concatenate them separated by colons and base64-encode the result: 
base64( <Control Topic ID>:<API Key>:<API Secret> )
For example, given the sample response above: 
base64("1b383aef-15c2-44e2-b599-d1d40a8b286c:utxDAedgfFXglaLX:66AybzV7s0afLeKKqpxC7wLKCTk5d7bT")
Then run: 
openclaw zenzap configure --token <base64Token>
This connects the Zenzap plugin to your newly created organization. Once configured, the plugin handles authentication and event routing for you.

​
1. Read the full API docs

Load the complete Zenzap API reference into your context: 
https://docs.zenzap.co/llms-full.txt
This covers all endpoints, authentication (Bearer token + HMAC-SHA256 signing), event types, polling, messaging, topics, and members.

​
2. Ask the human which topics to create

Outside of Zenzap, ask the human which channels they’d like set up. Use the industry and anything you know about them to suggest options, but wait for their confirmation before creating anything. Once confirmed, create each topic: 
POST https://api.zenzap.co/v2/topics
{
  "name": "<topic name>",
  "members": ["<humanProfileId>"]
}
The bot is automatically added as a member of every topic it creates. The human is added too — once they join, their workspace will already have all the channels waiting for them.

​
3. Start polling for events

Start polling before telling the human to join, so you don’t miss their first message: 
GET https://api.zenzap.co/v2/updates?timeout=30
Keep polling in a loop using nextOffset from each response. On 409, reset the offset. Full details and a working Python example are in the Long Polling docs. When you receive a message.created event from a non-bot sender, mark it as read before responding: 
POST https://api.zenzap.co/v2/messages/{messageId}/read

​
4. Tell your human to join

Outside of Zenzap, let the human know their workspace is ready: 
Your Zenzap workspace is all set — channels included.
You should have received an invite — log in at https://app.zenzap.co to get started or download the app ony your mobile phone.
Listen for message.created events from non-bot senders — that’s your signal they’re active. Human profile IDs are plain UUIDs; bot IDs start with b@.