Endpoints for AI agents to programmatically set up Zenzap organizations. Use `POST /v2/agentic/organization/create` to create an organization, install a bot, and invite a human user in a single request — no authentication required.
openapi: 3.0.3
info:
title: Zenzap External Integration Agentic API
description: "API for external applications to integrate with Zenzap.\n## Getting Started\nWelcome to the Zenzap External Integration API documentation. This API is used to integrate with Zenzap.\nAs a context we would like to familiarize you with the Zenzap platform and how it works.\nZenzap is a platform for creating and managing topics and messages.\nTopics (Zenzap term for group chats/channels/conversations) are used to create and manage conversations with your team. Topics are used to group messages and tasks together.\nMessages are used to send and receive messages with your team.\nTasks are used to create and manage tasks with your team.\nMembers are used to manage your team members.\nAPI keys are used to authenticate your requests to the Zenzap API.\nAPI keys are created and managed by the Zenzap admin user.\n\nWhen you create a new API key, it would create a new bot user in Zenzap, on which behalf you can send messages, create topics, create tasks and manage members.\nAll actions you perform with the API key will be performed on behalf of the bot user.\nThe bot can be used within the scope of your organization. You can create topics, send messages, create tasks and manage members on behalf of the bot.\n1. On a Zenzap admin user, go to https://app.zenzap.co/console\n2. Create a new API key with the needed permissions\n3. Copy the API key and secret from the API key settings\n4. For each request:\n - Add the Authorization header with your API key\n - Generate a Unix timestamp in milliseconds\n - Calculate the HMAC-SHA256 signature:\n - For POST/PUT/PATCH/DELETE: Sign `{timestamp}.{body}`\n - For GET: Sign `{timestamp}.{uri}` (e.g., `/v2/members?limit=10`)\n - Add the X-Signature header with the hex-encoded signature\n - Add the X-Timestamp header with the timestamp used in the payload\n\n## Authentication\nAll API endpoints require two forms of authentication:\n\n1. **Bearer Token**: Include your API key in the Authorization header:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\n2. **Request Signing**: Include an HMAC signature and timestamp in headers:\n```\nX-Signature: <HMAC-SHA256 hex-encoded signature>\nX-Timestamp: <Unix timestamp in milliseconds>\n```\nThe signature includes a timestamp for replay protection. Requests older than 5 minutes are rejected.\n\nThe signature payload differs by HTTP method:\n- **POST/PUT/PATCH/DELETE requests**: Sign `{timestamp}.{body}`\n- **GET requests**: Sign `{timestamp}.{uri}`\n\nThe signature is calculated using HMAC-SHA256 with your API secret.\n\n **How to calculate:**\n 1. Get the current Unix timestamp in milliseconds\n 2. Determine the payload:\n - **POST/PUT/PATCH/DELETE**: Use `{timestamp}.{body}` (e.g., `1699564800000.{\"topicId\":\"123\"}`)\n - **GET**: Use `{timestamp}.{uri}` (e.g., `1699564800000./v2/members?limit=10`)\n 3. Calculate HMAC-SHA256 of the payload using your API secret\n 4. Hex-encode the result (64 character lowercase string)\n 5. Include timestamp in X-Timestamp header\n\n **Example (Python):**\n ```python\n import json\n import hmac\n import hashlib\n import time\n import requests\n\n def create_topic(name: str, members: list[str], description: str = None, external_id: str = None) -> dict:\n \"\"\"Create a topic in Zenzap with HMAC signature and replay protection.\"\"\"\n\n # Build request body\n body = {\n \"name\": name,\n \"members\": members,\n }\n if description:\n body[\"description\"] = description\n if external_id:\n body[\"externalId\"] = external_id\n\n # Serialize body (no spaces for consistent signing)\n body_json = json.dumps(body, separators=(\",\", \":\"))\n\n # Get timestamp for replay protection\n timestamp = int(time.time() * 1000) # Unix milliseconds\n\n # Create HMAC-SHA256 signature with timestamp\n signature_payload = f\"{timestamp}.{body_json}\"\n signature = hmac.new(\n API_SECRET.encode(),\n signature_payload.encode(),\n hashlib.sha256\n ).hexdigest()\n\n # Make request\n headers = {\n \"Authorization\": f\"Bearer {API_KEY}\",\n \"Content-Type\": \"application/json\",\n \"X-Signature\": signature,\n \"X-Timestamp\": str(timestamp),\n }\n\n response = requests.post(f\"{BASE_URL}/v2/topics\", headers=headers, data=body_json)\n response.raise_for_status()\n return response.json()\n ```\n\n **Note:** Our API documentation tools cannot automatically generate HMAC signatures. You will need to calculate this manually or use a tool like Postman with pre-request scripts.\n\n\n## Rate Limits\nAPI requests are rate limited per organization. Contact support for specific limits.\n"
version: 2.0.0
contact:
name: Zenzap Support
url: https://zenzap.co/support
servers:
- url: https://api.zenzap.co
description: Production server
security:
- bearerAuth: []
hmacSignature: []
- oauth2ClientCredentials: []
tags:
- name: Agentic
description: 'Endpoints for AI agents to programmatically set up Zenzap organizations.
Use `POST /v2/agentic/organization/create` to create an organization, install a bot, and invite a human user in a single request — no authentication required.
'
paths:
/v2/agentic/organization/create:
post:
summary: Create organization
description: 'Allows an external AI agent to programmatically create a Zenzap organization,
install a bot (the agent itself), and invite a human user — all in a single request.
**Authentication:** None required. This endpoint is publicly accessible.
**Rate limit:** 1 request per minute per IP.
Supports two content types:
- `application/json` — for requests without a logo
- `multipart/form-data` — for requests that include a company logo (`filePart`)
Once you receive the `201` response, use the returned `credentials` to authenticate
all subsequent API calls. See [Authentication](/api-reference/authentication) for details.
'
operationId: createAgenticOrganization
tags:
- Agentic
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgenticOrganizationCreateRequest'
example:
companyName: Acme Corp
humanEmail: founder@acme.com
companySize: 50
industry: Software
botName: Acme Assistant
multipart/form-data:
schema:
type: object
properties:
filePart:
type: string
format: binary
description: Company logo image. Max 5 MB. Optional.
metadata:
$ref: '#/components/schemas/AgenticOrganizationCreateRequest'
encoding:
metadata:
contentType: application/json
responses:
'201':
description: Organization created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AgenticOrganizationCreateResponse'
example:
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
'400':
description: Validation error
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
companyNameRequired:
summary: Missing company name
value:
message: companyName is required
companyNameTooLong:
summary: Company name too long
value:
message: companyName exceeds max length
invalidEmail:
summary: Invalid email
value:
message: invalid humanEmail
invalidCompanySize:
summary: Invalid company size
value:
message: companySize must be a positive integer
industryRequired:
summary: Missing industry
value:
message: industry is required
botNameRequired:
summary: Missing bot name
value:
message: botName is required
unableToCreate:
summary: Conflict (email or domain already in use)
value:
message: Unable to create organization
'429':
description: Rate limit exceeded (1 request per minute per IP)
components:
schemas:
AgenticOrganizationCreateResponse:
type: object
properties:
organizationId:
type: string
format: uuid
description: UUID of the newly created organization.
example: 067d0b2f-1ee8-49f2-bb09-e2d964c8cf6b
botProfileId:
type: string
description: The bot's identity (format `b@<uuid>`). Use as `senderId` filter when polling.
example: b@f951b968-bf80-4ee6-bbbe-6ca338f57fc6
channelId:
type: string
format: uuid
description: The bot's control channel ID (same as the `Control Topic ID` credential).
example: 1b383aef-15c2-44e2-b599-d1d40a8b286c
humanProfileId:
type: string
format: uuid
description: The pending profile ID of the invited human. Use this to identify the human once they join.
example: a3c2e1d0-9f8b-4e7a-b6c5-d4e3f2a1b0c9
credentials:
type: array
description: API credentials for the bot. Store the API Secret securely.
items:
type: object
properties:
label:
type: string
example: API Key
value:
type: string
example: utxDAedgfFXglaLX
AgenticOrganizationCreateRequest:
type: object
required:
- companyName
- humanEmail
- companySize
- industry
- botName
properties:
companyName:
type: string
maxLength: 100
description: Display name of the organization.
example: Acme Corp
humanEmail:
type: string
format: email
description: The human user who will receive an invite and become the org's first member.
example: founder@acme.com
companySize:
type: integer
minimum: 1
description: Number of employees. Mapped to a size range.
example: 50
industry:
type: string
description: Free-text industry description (e.g. "Software", "Healthcare").
example: Software
botName:
type: string
description: Display name for the agent bot installed in the organization.
example: Acme Assistant
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Bearer token for the request. Two flavors:
- **Static API key** — pass your API key (the value returned as `apiKey` when the bot was created). Must be paired with `X-Signature` + `X-Timestamp` (the `hmacSignature` scheme).
- **OAuth access token** — pass the JWT returned by `POST /oauth/token`. No signature headers are required.
'
hmacSignature:
type: apiKey
in: header
name: X-Signature
description: 'HMAC-SHA256 signature for request verification. Required **only** when authenticating with a static API key. Omit when using an OAuth access token.
'
oauth2ClientCredentials:
type: oauth2
description: 'OAuth 2.0 `client_credentials` grant for API-key bots. Use the `clientId` and `clientSecret` returned when the bot was created (or rotated) to mint short-lived access tokens. See [Authentication](/api-reference/authentication) for details.
Access tokens are bearer JWTs and expire after 1 hour. There is no refresh token — re-mint with the client credentials when the token expires.
'
flows:
clientCredentials:
tokenUrl: https://api.zenzap.co/oauth/token
scopes:
channel:list: List topics the bot belongs to
channel:read: Read topic metadata
channel:write: Create/update topics and manage members
message:read: Read messages
message:send: Send messages
message:write: Edit / delete / mark-delivered / mark-read messages
reaction:write: Add and remove reactions on messages
task:read: Read tasks
task:write: Create / update / delete tasks
poll:write: Create polls and cast / retract votes
member:read: List organization members
updates:read: Long-poll for outbound events