# LotsAgent API Build and run LotsAgent agents from your own code or AI assistant. The same tools are served over MCP and REST. ## MCP `https://api.lotsagent.com/mcp` Add this server to Claude, ChatGPT or any MCP client. You sign in with your LotsAgent account and choose what the connection may do. ## REST `https://api.lotsagent.com/api/v1/lotsagent/...` Send a workspace API key or an OAuth access token as a Bearer token. Responses are { success, data, meta }; errors are { success: false, error: { code, message } }. ## Permissions Each tool needs one permission: read, write, send, money or delete. A connection or key can use only the permissions it was given, and your role in each workspace still applies. ## Tools ### accept_invitation Accept an invitation with the token from its email link, as the signed-in person. The account email must match the invited email. Joining never lowers a role you already have. Permission: write - `POST /api/v1/lotsagent/invitations/accept` ### accept_workspace_handover Accept a hand-over (confirm true) as the person it was sent to. Permission: write - `POST /api/v1/lotsagent/handover/accept` ### add_agent_read_action Add one action that reads from your API (an HTTP GET) to the agent by hand: an https URL template with {placeholders} in the path, query parameters and fixed headers (no keys). It is saved as a read action unless you set permission_class. Do not ask the person for a key in chat: leave auth.secret out and tell them to add the key on the agent's Tools tab. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/actions/read` ### add_agent_tool Give an agent one or more tools of a connected app. get_app_tools lists an app's tools and their ids; list_connections shows your app accounts. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/tools` ### add_agent_write_action Add one action that changes something in your API (POST, PUT, PATCH or DELETE) to the agent by hand: an https URL template with {placeholders} in the path, query parameters, fixed headers (no keys) and a JSON body schema. permission_class defaults from the method (DELETE delete, others write); writes, sends and deletes ask the person to Confirm. Do not ask the person for a key in chat: leave auth.secret out and tell them to add the key on the agent's Tools tab. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/actions/write` ### add_knowledge_text Add pasted text to what an agent knows, with a title and, if it has one, the public page it comes from (answers link to it). It is ready to answer from once indexed, usually within a minute. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/knowledge/text` ### add_knowledge_website Add a website to what an agent knows: one page, the pages under an address, or a sitemap. Reading starts at once and continues in the background (up to 200 pages); answers link the page they come from. Optionally re-sync it daily or weekly. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/knowledge/websites` ### archive_agent Archive an agent: it leaves your Agents list and stops answering everywhere it is live. restore_agent brings it back. Permission: delete - `DELETE /api/v1/lotsagent/agents/:agent_id` ### assign_skill_to_agent Assign Skill to Agent: Assign a skill to an agent. If agent_id is omitted, uses the current executing agent. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/skills` ### cancel_invitation Cancel a pending invitation; its link stops working. Owner or admin required. Permission: write - `DELETE /api/v1/lotsagent/workspaces/:workspace_id/invitations/:invitation_id` ### cancel_workspace_handover Cancel the pending hand-over. Owner only. Permission: write - `DELETE /api/v1/lotsagent/workspaces/:workspace_id/handover` ### check_handle Check whether a handle is free. The handle is the agent's address name: 3 to 50 lowercase letters, numbers and hyphens. Permission: read - `GET /api/v1/lotsagent/agents/handle-available` ### create_agent Create an agent as a draft, like the first steps of New agent. Pick a template for its starting instructions: help (a help center from your docs), app (an assistant inside your app), workflow (runs tasks on a schedule or from your systems) or blank. Next: add knowledge, test it, then put it live from Deploy. Permission: write - `POST /api/v1/lotsagent/agents` ### create_skill Create Skill: Create a new skill with instructions and optional references/scripts/assets. Permission: write - `POST /api/v1/lotsagent/skills` ### create_task Save a task for an agent: instructions it runs by hand, once at a set time, or on a schedule, such as every weekday at 9. A scheduled run has nobody to press Confirm, so an action that needs Confirm stops the run and waits for you. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/tasks` ### create_workspace Create a team workspace, or a client workspace for agents you build for a client. You become its owner and its payer. Members are unlimited. Permission: write - `POST /api/v1/lotsagent/workspaces` ### decline_workspace_handover Decline a hand-over as the person it was sent to. Permission: write - `POST /api/v1/lotsagent/handover/decline` ### delete_skill Delete Skill: Permanently delete an Agent Skill from the user's library. This also removes any assignments to agents. Only the skill owner can delete it. Use when the user explicitly wants to remove a skill. Permission: delete - `DELETE /api/v1/lotsagent/skills/:skill_id` ### delete_task Delete a saved task. Its past runs stay in Activity. Permission: delete - `DELETE /api/v1/lotsagent/tasks/:task_id` ### disconnect_app Disconnect one of your app accounts. Every agent that used it loses those tools until you connect it again. Permission: delete - `DELETE /api/v1/lotsagent/connections/:connection_id` ### get_agent One agent's Overview: status, where it is live, its model, instructions and personality, what it knows (files, websites, indexing), its skills and tools, runs in the last 7 days, and whether it has been tested. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id` ### get_agent_memory What an agent remembers about you (Settings > Memory): notes about you and what it learned in your chats. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/memory` ### get_api_keys_link The console page where you make an API key. A new key is shown once, in your browser, never in a chat. Permission: read - `GET /api/v1/lotsagent/api-keys/link` ### get_app_tools An app's tools with their ids, to give an agent with add_agent_tool. Permission: read - `GET /api/v1/lotsagent/apps/:app_key/tools` ### get_billing Your plan, the credits it includes, your credit balance and, during the trial, the days and credits left. Buying credits and changing plans happen on the Billing page. Permission: read - `GET /api/v1/lotsagent/billing` ### get_connect_link The console page where you connect an app: signing in to an app happens in your browser, never in a chat. Permission: read - `GET /api/v1/lotsagent/apps/:app_key/connect-link` ### get_conversation One chat from list_agent_conversations, in order: the person's messages, the agent's replies, and each tool step with how it ended and what happened on its Confirm card. Shown from the moment the person accepted the notice. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/conversations/:conversation_id` ### get_credits_link The Billing page, where you buy credits. Paying happens there, never in a chat. Permission: read - `GET /api/v1/lotsagent/billing/credits-link` ### get_knowledge_item One file or pasted text in an agent's knowledge: its details, its text where it has one, and its indexing state. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/knowledge/files/:file_id` ### get_knowledge_website One website in an agent's knowledge: its sync state, schedule and the pages read from it (up to 100). Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/knowledge/websites/:website_id` ### get_plan_link The Billing page, where you choose or change your plan. Permission: read - `GET /api/v1/lotsagent/billing/plan-link` ### get_profile Who you are signed in as, and your workspaces with your role in each. Permission: read - `GET /api/v1/lotsagent/me` ### get_sidebar_settings An agent's sidebar settings as Deploy > Sidebar shows them: on or off, test mode, the sites it may appear on, who can chat, sign-in, limits and privacy, its look, and the two-line snippet to add it to a site. Signing keys are listed without their secrets. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/sidebar` ### get_skill Get Skill Details: Get full metadata and instruction payload for a skill by ID. Permission: read - `GET /api/v1/lotsagent/skills/:skill_id` ### get_task One saved task with its instructions, schedule and last runs. Permission: read - `GET /api/v1/lotsagent/tasks/:task_id` ### get_task_run One run of a task: its status, what it did, its result and what it cost. Permission: read - `GET /api/v1/lotsagent/task-runs/:run_id` ### get_usage Requests and credits used, as the Usage page shows them: in total, by agent, by model or by day. For one agent, give agent_id. Permission: read - `GET /api/v1/lotsagent/usage` ### get_web_address An agent's own web address as Deploy > Web address shows it: whether it is public, its lotsagent.com address, its custom domain with the DNS records to add, and whether people sign in through your app. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/web-address` ### get_workspace One workspace with your role. Permission: read - `GET /api/v1/lotsagent/workspaces/:workspace_id` ### get_workspace_handover The pending hand-over of a workspace. Permission: read - `GET /api/v1/lotsagent/workspaces/:workspace_id/handover` ### grant_support_access Let LotsTech support (support@lotstech.com) into one workspace for a limited time so they can look at a problem and fix it. Support joins as Support and can never change billing, payments, the owner or the team. Without confirmed: true it changes nothing and returns the consent text; grant only after the person has read it and said yes. duration is 24h, 7d (default) or 30d. may_publish (default false) lets support publish fixes live. Granting again while access is on changes the end time. LotsTech support hears about it by email. Permission: send - `POST /api/v1/lotsagent/workspaces/:workspace_id/support-access` ### import_openapi_actions Add operations of an OpenAPI 3 document to the agent as actions. operations: the keys from preview_openapi_actions ("GET /orders/{id}"), each optionally with its own name, permission_class (read, write, send, delete), confirm_override (default, always, never) and audience (owner, everyone). Writes, sends and deletes ask the person to Confirm by default. Do not ask the person for a key in chat: leave auth.secret out and tell them to add the key on the agent's Tools tab. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/actions/import` ### import_skill Import Skill from GitHub: Import a skill definition from a GitHub repository URL. Permission: write - `POST /api/v1/lotsagent/skills/import` ### invite_workspace_member Invite someone to a workspace by email, with or without a Lots account. They get an email link, sign in or sign up with that email, and join with the role you chose. Inviting an email that already has a pending invitation sends a fresh link. owner cannot be invited. Owner or admin required. Members are unlimited. Permission: send - `POST /api/v1/lotsagent/workspaces/:workspace_id/invitations` ### leave_workspace Leave a workspace you were invited to; you lose access at once. The owner cannot leave their own workspace. Permission: write - `POST /api/v1/lotsagent/workspaces/:workspace_id/leave` ### list_activity What your agents did, newest first, as Activity shows it: chats, scheduled tasks and API calls, with status and credits. For one agent, give agent_id. Permission: read - `GET /api/v1/lotsagent/activity` ### list_agent_action_calls Recent calls of the agent's actions, newest first: action, where it ran, result, HTTP status, time and size. Never the arguments, the answer or keys. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/actions/calls` ### list_agent_actions The agent's own HTTP actions (its own API as tools): name, method, URL, permission class, whether a call asks for Confirm, who can use it, and whether a key is saved. Keys are never shown. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/actions` ### list_agent_api_keys An agent's own API keys: name, the first characters, when last used. Never the key itself. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/api-keys` ### list_agent_conversations The chats people had with one agent in its sidebar and on its web address, newest first: date, person (name or email when the app signed them in, else Visitor) and message count. Only chats whose person was told by the agent's notice that their chat may be read, from that moment on; reading is off until the owner turns on "Let people know I may read their chats". search matches the person and the text of the newest chats. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/conversations` ### list_agent_skills List Agent Skills: List skills currently assigned to an agent. If agent_id is omitted, uses the current executing agent. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/skills` ### list_agent_tools The tools an agent can use, as its Tools tab shows them: each app tool with whether it is on and required, plus which of your app accounts it uses. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/tools` ### list_agents List your agents as the Agents page shows them: name, handle, status (live, testing, draft or archived), where each one is live (sidebar, web address, API or MCP, schedules), conversations and credits in the last 7 days, and when it was last active. Archived agents are listed only with archived set to true. Permission: read - `GET /api/v1/lotsagent/agents` ### list_available_apps The apps an agent can use as tools, as the Tools page lists them, with whether you have connected each one. Permission: read - `GET /api/v1/lotsagent/apps` ### list_connections Your app accounts connected to LotsAgent: which app, which account, and when it was connected. Permission: read - `GET /api/v1/lotsagent/connections` ### list_conversations How many sidebar and web address conversations each agent had per day over the last 14 days. Counts only, never what was said. Permission: read - `GET /api/v1/lotsagent/conversations` ### list_credit_transactions Credits added and used, newest first. Permission: read - `GET /api/v1/lotsagent/billing/transactions` ### list_invitations List a workspace's invitations (pending by default; status all for history). Owner or admin required. Permission: read - `GET /api/v1/lotsagent/workspaces/:workspace_id/invitations` ### list_knowledge What an agent knows, as its Knowledge tab shows it: files and pasted text with their indexing state, and websites with their pages, schedule and last sync. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/knowledge` ### list_knowledge_gaps Questions people asked that the agent's knowledge could not answer, most asked first, so you know what to add. Open ones by default. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/knowledge-gaps` ### list_models The models a new agent can run on, and the default. Pass one of them as model to create_agent or update_agent. Permission: read - `GET /api/v1/lotsagent/models` ### list_skills List Skills: List skills available to the user and platform, including optional filtering. Permission: read - `GET /api/v1/lotsagent/skills` ### list_support_access Whether LotsTech support has access to this workspace, until when, and what support did there. available false means support access is not set up yet. Permission: read - `GET /api/v1/lotsagent/workspaces/:workspace_id/support-access` ### list_task_runs A saved task's runs, newest first, with status, when and how long. Permission: read - `GET /api/v1/lotsagent/tasks/:task_id/runs` ### list_tasks An agent's saved tasks (Deploy > Schedules): each with how it runs (by hand, once or on a schedule), whether it is on, and its next run. Permission: read - `GET /api/v1/lotsagent/agents/:agent_id/tasks` ### list_usage_logs Each request with its model, tokens and credits, newest first. Permission: read - `GET /api/v1/lotsagent/usage/logs` ### list_workspace_api_keys Your API keys from Settings, API Keys: name, the first characters, access, when last used and when they expire. Never the key itself. Permission: read - `GET /api/v1/lotsagent/api-keys` ### list_workspace_members List the people in a workspace with their email, name and role. Pending invitations are in list_invitations. Permission: read - `GET /api/v1/lotsagent/workspaces/:workspace_id/members` ### list_workspaces List the LotsAgent workspaces you belong to, with your role in each (owner, admin, member or viewer). Your personal workspace is always there; team and client workspaces follow. Permission: read - `GET /api/v1/lotsagent/workspaces` ### preview_openapi_actions Read an OpenAPI 3 document (its https URL, or the JSON or YAML text) and list its operations as actions the agent could use, with the suggested auth. Nothing is saved. Then call import_openapi_actions with the operations to add. Permission: read - `POST /api/v1/lotsagent/agents/:agent_id/actions/openapi` ### preview_workspace_handover What a hand-over moves, for the person it was sent to. Permission: read - `POST /api/v1/lotsagent/handover/preview` ### reindex_knowledge_item Index a knowledge file again, for example after it failed. It keeps answering from the old index until the new one is ready. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/knowledge/files/:file_id/reindex` ### remove_agent_action Remove one action from the agent, with its saved key. Permission: delete - `DELETE /api/v1/lotsagent/agents/:agent_id/actions/:action_id` ### remove_agent_tool Take a tool off an agent. add_agent_tool puts it back. Permission: write - `DELETE /api/v1/lotsagent/agents/:agent_id/tools/:tool_id` ### remove_custom_domain Take an agent off its custom domain. The domain stops answering at once. Permission: delete - `DELETE /api/v1/lotsagent/agents/:agent_id/custom-domain` ### remove_knowledge_item Remove a file or pasted text from an agent's knowledge. The agent stops answering from it at once. Permission: delete - `DELETE /api/v1/lotsagent/agents/:agent_id/knowledge/files/:file_id` ### remove_knowledge_website Remove a website and every page read from it from an agent's knowledge. The agent stops answering from it at once. Permission: delete - `DELETE /api/v1/lotsagent/agents/:agent_id/knowledge/websites/:website_id` ### remove_skill_from_agent Remove Skill from Agent: Remove a skill assignment from an agent. If agent_id is omitted, uses the current executing agent. Permission: write - `DELETE /api/v1/lotsagent/agents/:agent_id/skills/:skill_id` ### remove_workspace_member Remove someone from a workspace: they lose access at once. The agents they built stay. The owner cannot be removed, and an admin cannot remove another admin. Owner or admin required. To come back they need a new invitation. Permission: delete - `DELETE /api/v1/lotsagent/workspaces/:workspace_id/members/:user_id` ### resend_invitation Email a pending invitation again with a fresh link (the old link stops working) and a new 7-day expiry. Owner or admin required. Permission: send - `POST /api/v1/lotsagent/workspaces/:workspace_id/invitations/:invitation_id/resend` ### restore_agent Bring an archived agent back to your Agents list as active. Where it was live stays off until you switch it on again. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/restore` ### revoke_agent_api_key Revoke one of an agent's API keys. Anything using it stops working at once. Permission: delete - `DELETE /api/v1/lotsagent/agents/:agent_id/api-keys/:key_id` ### revoke_support_access End LotsTech support's access to this workspace now. Support leaves the team at once. Permission: delete - `DELETE /api/v1/lotsagent/workspaces/:workspace_id/support-access` ### revoke_workspace_api_key Revoke one of your API keys. Anything using it stops working at once. Permission: delete - `DELETE /api/v1/lotsagent/api-keys/:key_id` ### run_task Run a saved task now, in the background. It costs credits like any run. The answer has a run id: get_task_run shows how it went. Permission: write - `POST /api/v1/lotsagent/tasks/:task_id/run` ### set_agent_mcp_access Switch on or off whether AI apps can connect to this agent as a tool over MCP (Deploy > API and MCP). Switching it on lets anyone you give the agent's MCP address to connect with their own sign-in. Permission: send - `PUT /api/v1/lotsagent/agents/:agent_id/mcp-access` ### set_custom_domain Put an agent on your own domain, such as help.example.com. The answer lists the DNS records to add; then verify_custom_domain. The agent must be public, or people must sign in through your app. Permission: send - `POST /api/v1/lotsagent/agents/:agent_id/custom-domain` ### set_web_address Make an agent public or private, and switch its lotsagent.com address on or off. A public agent on its address answers anyone who opens it, and you pay for those chats. Permission: send - `PATCH /api/v1/lotsagent/agents/:agent_id/web-address` ### start_workspace_handover Hand a workspace over to a client by email. Owner only. Permission: send - `POST /api/v1/lotsagent/workspaces/:workspace_id/handover` ### stop_agent Stop now: take an agent's sidebar off every site at once. Its settings are kept; update_sidebar_settings with enabled true puts it back. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/stop` ### sync_knowledge_website Read a website in an agent's knowledge again now (Re-sync now). Changed pages are updated and removed pages are dropped. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/knowledge/websites/:website_id/sync` ### test_agent Send an agent one message and read its reply, like its Test screen. It costs credits like any chat. Actions that need someone to press Confirm are not run; the reply says so. Pass session_id from the answer to continue the same chat. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/test` ### test_agent_action Call one action now with the given input and the saved key, like the Test button on the Tools tab. It reaches the real API, so a write really happens. Returns the HTTP status and the answer (capped). Permission: send - `POST /api/v1/lotsagent/agents/:agent_id/actions/:action_id/test` ### update_agent Change an agent's settings: name, description, status (draft or active), instructions, personality, model, role, tone or emoji. Only the fields you give change. Permission: write - `PATCH /api/v1/lotsagent/agents/:agent_id` ### update_agent_limits Change an agent's limits and privacy (Deploy > Sidebar, Limits and privacy): messages per person per day, the daily spend cap and when to email you, the timezone the day starts in, how long chats are kept, and the notice people see before they chat. Permission: write - `PATCH /api/v1/lotsagent/agents/:agent_id/limits` ### update_agent_look Change how an agent's sidebar looks (the Look tab): the button and its label, sidebar, inline or full screen, which side, the colour, the title, the welcome line and up to 4 starter questions. Only the fields you give change. The avatar is changed in the console. Permission: write - `PATCH /api/v1/lotsagent/agents/:agent_id/look` ### update_agent_memory Change what an agent remembers about you: replace or add to its memory, or set notes about you. Send empty text to clear it. Permission: write - `PATCH /api/v1/lotsagent/agents/:agent_id/memory` ### update_agent_read_action Change one read action (an HTTP GET): only the fields you send change. is_enabled false turns it off. A new auth.secret replaces the saved key; clear_secret true removes it. A write action is changed with update_agent_write_action. Permission: write - `PATCH /api/v1/lotsagent/agents/:agent_id/actions/:action_id/read` ### update_agent_tool Switch one of an agent's tools on or off, or mark it required. Permission: write - `PATCH /api/v1/lotsagent/agents/:agent_id/tools/:tool_id` ### update_agent_write_action Change one write action (POST, PUT, PATCH or DELETE): only the fields you send change. is_enabled false turns it off. A new auth.secret replaces the saved key; clear_secret true removes it. A read action is changed with update_agent_read_action. Permission: write - `PATCH /api/v1/lotsagent/agents/:agent_id/actions/:action_id/write` ### update_knowledge_gap Mark a knowledge gap covered (you added what answers it), ignored, or open again. Permission: write - `PATCH /api/v1/lotsagent/agents/:agent_id/knowledge-gaps/:gap_id` ### update_knowledge_item Change a knowledge file's title, description or public page link, or replace the content of pasted text or a text file (it is indexed again; the old version keeps answering until the new one is ready). Permission: write - `PATCH /api/v1/lotsagent/agents/:agent_id/knowledge/files/:file_id` ### update_knowledge_website Change how often a website in an agent's knowledge is read again: off, daily or weekly. Permission: write - `PATCH /api/v1/lotsagent/agents/:agent_id/knowledge/websites/:website_id` ### update_sidebar_settings Put an agent's sidebar live or take it off, switch test mode (works on localhost only), set the sites it may appear on, and choose whether anyone can chat without signing in. Going live, adding sites and letting anyone chat put the agent in front of people. Permission: write (send with some arguments) - `PATCH /api/v1/lotsagent/agents/:agent_id/sidebar` ### update_skill Update Skill: Update an existing Agent Skill's configuration, instructions, or metadata. Only the skill owner can update it. Use when the user wants to modify a skill they own. Permission: write - `PATCH /api/v1/lotsagent/skills/:skill_id` ### update_task Change a saved task: its name, instructions or schedule, or switch it on or off. Only the fields you give change. Permission: write - `PATCH /api/v1/lotsagent/tasks/:task_id` ### update_workspace Rename a workspace, or change its client's name and contact email. Owner or admin required. Permission: write - `PATCH /api/v1/lotsagent/workspaces/:workspace_id` ### update_workspace_member Change a member's role to admin, member or viewer. owner can never be granted and the owner's role cannot be changed; an admin cannot change another admin. Owner or admin required. Permission: delete - `PATCH /api/v1/lotsagent/workspaces/:workspace_id/members/:user_id` ### verify_custom_domain Check an agent's custom domain again: whether its DNS records are in place and its certificate is ready. Permission: write - `POST /api/v1/lotsagent/agents/:agent_id/custom-domain/verify`