This API enables AI agents and automation tools (e.g. OpenClaw, MCP servers, custom integrations) to act on behalf of SmartSaaS users. Agents use an API key scoped to a user/company to read and write data, manage projects, store research, and push real-time updates—all without requiring the user to be logged in.
Use cases
- OpenClaw & MCP-style tools: Agents that assist users by creating datasets, adding knowledge, managing projects, and streaming responses to the user's messaging UI.
- Research assistants: Store findings via
/research; results appear in the user's knowledge base. - Project automation: Create projects, work packages, and tasks; update task status.
- Real-time feedback: Use the OpenClaw webhook to push messages and task progress to the user's app in real time.
Authentication
All routes require API key authentication. Send the key in the Authorization header as Bearer <api-key> or as the raw key. The API key is bound to a user/company; requests operate in that context.
Permissions
Keys are scoped by permission: users:read, data:read, data:write, knowledge:read, knowledge:write, business_plans:read, business_plans:write, projects:read, projects:write, sales:read, sales:write, templates:read, templates:write, plus analytics:read, integrations:*, organiser:*, company:*, admin:* as configured. Configure permissions when creating keys in SmartSaaS.
Tool mapping (MCP / OpenClaw)
| Capability | Endpoint | Use case |
|---|---|---|
| List users | GET /protected/users |
Resolve recipients, team context |
| Push message | POST /protected/openclaw/webhook |
Stream replies to user's UI |
| Task progress | POST /protected/openclaw/webhook |
Update Agent Tasks board |
| List/create datasets | GET/POST /protected/data/folders |
Store agent outputs |
| Add data rows | POST /protected/data/folders/{id}/items |
Append scraped/processed data |
| List/add knowledge | GET/POST /protected/knowledge |
RAG, store findings |
| Post research | POST /protected/research |
Save research as knowledge |
| Manage business plans | GET/POST/DELETE /protected/business-plans |
Create/retrieve plans |
| Manage projects | GET/POST /protected/projects, work-packages, tasks |
Create tasks, update status |
| Project detail & completed | GET /protected/projects/{id}/detail, GET /protected/projects/completed/list |
Full project payload, completed list |
| Sales campaigns & CRM | GET/POST /protected/sales/campaigns, CRM, funnel, forecasts |
Campaigns, leads, analytics |
| Templates | GET/POST /protected/templates/* |
Email, document, webpage, invoice, media |
Agent webhook (real-time push)
Push messages and task progress to the user's app in real time. Used by OpenClaw, MCP servers, and other agents to stream responses and task updates to the user's messaging UI.
- Messages: Send
message,chunk(streaming),messageId,conversationId,done. - Task tracing: Send
taskId,status(started | in_progress | done),summaryto create/update Agent Tasks visible on the user's board. - Events are emitted to the user's socket room; the Resolver app receives
openclaw:messageandagent-task-updateevents. Permission: API key only (no extra permission).
Authorizations:
Request Body schema: application/json
| message | string Full message text |
| chunk | string Streaming chunk |
| messageId | string |
| conversationId | string Default: "openclaw" |
| done | boolean Default: false |
| taskId | string For task tracing |
| status | string Enum: "started" "in_progress" "done" |
| summary | string Task summary for Agent Tasks board |
Responses
Request samples
- Payload
{- "message": "string",
- "chunk": "string",
- "messageId": "string",
- "conversationId": "openclaw",
- "done": false,
- "taskId": "string",
- "status": "started",
- "summary": "string"
}List data folders
List datasets/folders for the user. Use to find where to store agent outputs or to browse existing data.
Permission: data:read
Authorizations:
query Parameters
| page | string Default: 1 |
| limit | string Default: 10 |
| sortBy | string Default: "updatedAt" |
| sortOrder | string Default: "desc" Enum: "asc" "desc" |
Responses
Create data folder
Create a dataset/folder. Use to store structured outputs (e.g. CSV, tables) from agent work. Body: title/name/dataTitle, dataTags, dataSchema, company, parentId.
Permission: data:write
Authorizations:
Request Body schema: application/json
| title | string |
| name | string |
| dataTitle | string |
| parentId | string |
| dataTags | Array of strings |
| dataSchema | Array of arrays |
| company | string |
Responses
Request samples
- Payload
{- "title": "string",
- "name": "string",
- "dataTitle": "string",
- "parentId": "string",
- "dataTags": [
- "string"
], - "dataSchema": [ ],
- "company": "string"
}Add item to data folder
Add a row/item to a dataset. Use to append agent-generated data (e.g. scraped records, analysis results).
Permission: data:write
Authorizations:
path Parameters
| folderId required | string |
Request Body schema: application/json
Responses
Request samples
- Payload
{ }Create knowledge article
Add a knowledge article. Use to store agent-generated docs, summaries, or reference material for the user.
Permission: knowledge:write
Authorizations:
Request Body schema: application/json
| title | string |
| content | string |
Responses
Request samples
- Payload
{- "title": "string",
- "content": "string"
}Post research (stored as knowledge)
Submit research findings; stored as a knowledge article. Use for research agents to save findings (title, findings/content/summary, source, url, sources).
Permission: knowledge:write
Authorizations:
Request Body schema: application/json
| title | string |
| findings | string |
| content | string |
| summary | string |
| source | string |
| url | string |
| sources | Array of arrays |
Responses
Request samples
- Payload
{- "title": "string",
- "findings": "string",
- "content": "string",
- "summary": "string",
- "source": "string",
- "url": "string",
- "sources": [ ]
}Create project
Create a project on behalf of the user. Body: title, description, tags, status, start_date, end_date.
Permission: projects:write
Authorizations:
Request Body schema: application/json
| title | string |
| description | string |
| tags | Array of arrays |
| status | string |
| start_date | string |
| end_date | string |
Responses
Request samples
- Payload
{- "title": "string",
- "description": "string",
- "tags": [ ],
- "status": "string",
- "start_date": "string",
- "end_date": "string"
}Create task
Add a task to a work package. Use for task automation or agent-created todos. Permission projects:write
Authorizations:
path Parameters
| projectId required | string |
| wpId required | string |
Request Body schema: application/json
Responses
Request samples
- Payload
{ }Add team member
Add team member(s) to a project. Request body accepts teamMember or teamMembers array. Permission projects:write
Authorizations:
path Parameters
| projectId required | string |
Request Body schema: application/json
Responses
Request samples
- Payload
{ }Get campaign by id
Body includes campaignId, optional pagination (page, limit, stageIndex). Permission sales:read
Authorizations:
Request Body schema: application/json
| campaignId required | string |
| page | integer |
| limit | integer |
| stageIndex | integer |
Responses
Request samples
- Payload
{- "campaignId": "string",
- "page": 0,
- "limit": 0,
- "stageIndex": 0
}Unified sales analytics
Query params align with GET /api/sales/analytics (e.g. startDate, endDate, filterType, forecastId, dataItemIds). Permission sales:read
Authorizations:
query Parameters
| startDate | string |
| endDate | string |
| filterType | string Enum: "day" "week" "month" |
| forecastId | string |
| dataItemIds | string Comma-separated Mongo ids |
Responses
Email, invoice, document, webpage templates and media. Permissions templates:read, templates:write.