The Basin connector lets your AI agent act in each user's Basin account. Each user connects their own Basin API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 20 tools.
- Tools
- 20
- What they doRead · write · destructive
- 9 · 7 · 49 read7 write4 destructive
- Users sign in with
- API key
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Basin connection
In AgentKit > Connections, create a Basin connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'basin'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Basin:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'basin_list_domains',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "basin"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Basin:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="basin_list_domains",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Basin credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolbasin_get_formGet one form's settings by its ID.Read-onlyGet Form
Get one form's settings by its ID. Returns the form record: id, uuid, name, project_id and project_name, timezone, redirect_url, notification and autoreply settings, spam protection flags, retention_days, form_webhooks, and inbox, spam and trash counts. Use basin_list_forms to find the ID. Use basin_list_submissions for the form's submissions.
Inputs
form_idstringrequired- ID of the form to retrieve. Use the numeric id field returned by basin_list_forms. Example: 73320.
basin_get_mail_templateGet one email template by its ID.Read-onlyGet Mail Template
Get one email template by its ID. Returns the mail template's id, name, project_id, body (the latest submitted HTML, or the approved HTML when nothing is pending), created_at, and updated_at. Use basin_list_mail_templates to find the ID.
Inputs
mail_template_idintegerrequired- ID of the mail template to retrieve. Use the id field returned by basin_list_mail_templates. Example: 512.
basin_get_projectGet one project by its ID.Read-onlyGet Project
Get one project by its ID. Returns the project's id, name, created_at, and updated_at. Use basin_list_projects to find the ID.
Inputs
project_idstringrequired- ID of the project to retrieve. Use the id field returned by basin_list_projects. Example: 1024.
basin_get_submissionGet one form submission by its ID.Read-onlyGet Submission
Get one form submission by its ID. Returns the submission: id, email, payload_params (the submitted field values), form_id, form name and uuid, spam, read and trash flags, spam_reason, ip, referrer, user_agent, attachments, webhook_sent_at, and timestamps. Use basin_list_submissions to find the ID or to search across submissions.
Inputs
submission_idintegerrequired- ID of the submission to retrieve. Use the id field returned by basin_list_submissions. Example: 61109858.
basin_list_domainsList the custom email sending domains available to the account, one page at a time, optionally filtered by a search term.Read-onlyList Domains
List the custom email sending domains available to the account, one page at a time, optionally filtered by a search term. Returns a page of domain records with pagination metadata. Use this to find a domain_id for a form's custom sending domain (set through basin_update_form's additional_settings).
Inputs
pageinteger- Page number of domains to return, starting at 1. Omit for the first page. Check the response's pagination metadata to see whether more pages exist. Example: 2.
querystring- Search term that filters domains by id or name. Example: example.com.
basin_list_formsList the forms the API key can access, one page at a time, optionally filtered by a search term.Read-onlyList Forms
List the forms the API key can access, one page at a time, optionally filtered by a search term. Returns a page of form records with pagination metadata. Use this to find a form's id. Use basin_get_form for one form's full settings.
Inputs
pageinteger- Page number of forms to return, starting at 1. Omit for the first page. Check the response's pagination metadata to see whether more pages exist. Example: 2.
querystring- Search term that filters forms by id, name, uuid, or project_id. Example: Contact.
basin_list_mail_templatesList the email templates in a project, one page at a time.Read-onlyList Mail Templates
List the email templates in a project, one page at a time. Returns mail_templates (id, name, project_id, body, created_at, updated_at) and meta with count, page, and per_page. Use this to find a template id for a form's notification or autoreply email. Use basin_get_mail_template for one template.
Inputs
project_idintegerrequired- ID of the project the mail templates belong to. Use the id field returned by basin_list_projects. Example: 1024.
pageinteger- Page number of mail templates to return, starting at 1. Omit for the first page. Check the response's pagination metadata to see whether more pages exist. Example: 2.
page_sizeinteger- Number of templates per page, up to 20. Example: 20.
basin_list_projectsList the projects (groups of forms) the API key can access, one page at a time, optionally filtered by a search term.Read-onlyList Projects
List the projects (groups of forms) the API key can access, one page at a time, optionally filtered by a search term. Returns a page of project records with pagination metadata. Use this to find a project's id for basin_create_form or basin_list_mail_templates. Use basin_get_project for one project.
Inputs
pageinteger- Page number of projects to return, starting at 1. Omit for the first page. Check the response's pagination metadata to see whether more pages exist. Example: 2.
querystring- Search term that filters projects by id or name. Example: Marketing site.
basin_list_submissionsList form submissions, optionally for one form, filtered by status, search text, or date range, and sorted.Read-onlyList Submissions
List form submissions, optionally for one form, filtered by status, search text, or date range, and sorted. Returns a page of submissions, each with its id, submitted field values, spam, read and trash flags, and timestamps, with pagination metadata and inbox, spam and trash counts. Use this to browse or search submissions. Use basin_get_submission for one submission's full detail.
Inputs
date_rangestring- Only return submissions in this date range, written as 'YYYY-MM-DD to YYYY-MM-DD' with spaces around 'to' (it is sent as YYYY-MM-DD+to+YYYY-MM-DD, the format Basin documents). Dates use the form's time zone, or the account's time zone when no form_id is given. Example: 2026-01-01 to 2026-01-31.
filter_bystring- Which submissions to return: new (the inbox), spam, trash, or all. Example: new.one of
newspamtrashall form_idstring- ID of the form whose submissions to list. Use the id from basin_list_forms; Basin's docs also describe it as the ID in the form's endpoint URL (https://usebasin.com/f/FORM_ID). Leave out with an Account API Key to list across all forms; a Form API Key always returns its own form's submissions and ignores this. Example: 73320.
order_bystring- Sort order: date_asc, date_desc, email_asc, or email_desc. Example: date_desc.one of
date_ascdate_descemail_ascemail_desc pageinteger- Page number of submissions to return, starting at 1. Omit for the first page. Check the response's pagination metadata to see whether more pages exist. Example: 2.
querystring- Text to search for in submissions, such as a name or email address. Example: jane@example.com.
basin_create_formCreate a new form in a Basin project, with optional notification, autoreply, and spam protection settings.WriteCreate Form
Create a new form in a Basin project, with optional notification, autoreply, and spam protection settings. Returns the form record: id, uuid, name, project_id and project_name, timezone, redirect_url, notification and autoreply settings, spam protection flags, retention_days, form_webhooks, and inbox, spam and trash counts. The uuid is the form's endpoint ID (https://usebasin.com/f/<uuid>). Use basin_update_form to change an existing form. Form Studio fields cannot be added through the API; build them in the Basin dashboard.
Inputs
namestringrequired- Name of the form as shown in the Basin dashboard. Example: Contact form.
additional_settingsobject- Any other form attribute from Basin's API reference, as a JSON object merged into the form. Use it for settings that have no input above, such as redirect page text and colors (redirect_heading, redirect_message, button_background_color), mail templates (notification_mail_template_id, auto_response_mail_template_id), a custom sending domain (domain_id, domain_email), or use_ajax. Inputs above win over the same key here. Example: {"redirect_heading": "Thanks!", "button_background_color": "#24292E"}.
allowed_domainsarray- List of website domains allowed to submit to this form. Sending a list replaces the current one. Example: ["example.com", "www.example.com"].
autoreplyboolean- Set true to send an automatic reply email to the person who submitted the form, false to turn it off. Example: true.
autoreply_bodystring- Body text of the automatic reply sent to the submitter. Example: We received your message and will reply within one business day.
autoreply_from_namestring- Sender name shown on the automatic reply. Example: Acme Support.
autoreply_subjectstring- Subject line of the automatic reply sent to the submitter. Example: Thanks for contacting us.
blocked_domainsarray- List of domains whose submissions are blocked. Sending a list replaces the current one. Example: ["spam-domain.test"].
content_blacklistarray- List of words or phrases that mark a submission as spam when they appear in it. Sending a list replaces the current one. Example: ["casino", "crypto giveaway"].
duplicate_filterboolean- Set true to filter out duplicate submissions, false to accept them. Example: true.
force_hcaptchaboolean- Set true to require hCaptcha on submissions to this form. Example: false.
force_recaptchaboolean- Set true to require Google reCAPTCHA on submissions to this form. Example: false.
honeypot_fieldstring- Name of a hidden honeypot input in your HTML form. Submissions that fill it in are treated as spam. Example: _gotcha.
notification_bcc_emailsstring- Comma-separated list of 'bcc' recipients for notification emails. Sending a list replaces the current bcc recipients; leave out to keep them. New addresses must be verified. Example: archive@example.com.
notification_cc_emailsstring- Comma-separated list of 'cc' recipients for notification emails. Sending a list replaces the current cc recipients; leave out to keep them. New addresses must be verified. Example: manager@example.com.
notification_emailsstring- Comma-separated list of 'to' recipients for new-submission notification emails. Sending a list replaces the current recipients; leave out to keep them. Newly added addresses must be verified before they receive notifications. To remove all recipients, send {"notification_emails": ""} in additional_settings. Example: sales@example.com,ops@example.com.
notification_from_namestring- Sender name shown on notification emails. Example: Website Forms.
notification_subjectstring- Subject line of the notification email sent for each new submission. Example: New website lead.
project_idinteger- ID of the project the form belongs to. Use the id field returned by basin_list_projects. Example: 1024.
redirect_urlstring- URL Basin redirects the visitor to after a successful submission. Example: https://example.com/thanks.
retention_daysinteger- Number of days Basin keeps submissions for this form before deleting them. Example: 90.
smtp_email_validationboolean- Set true to check submitted email addresses against their mail server before accepting the submission. Example: true.
timezonestring- Time zone used for the form's dates and date-range filters, as Basin stores it (for example the zone name shown in the form settings). Example: Eastern Time (US & Canada).
basin_create_mail_templateCreate an HTML email template in a project, for use as a form's notification or autoreply email.WriteCreate Mail Template
Create an HTML email template in a project, for use as a form's notification or autoreply email. Returns the mail template's id, name, project_id, body (the latest submitted HTML, or the approved HTML when nothing is pending), created_at, and updated_at. Use basin_update_mail_template to change an existing template.
Inputs
namestringrequired- Name of the mail template, up to 100 characters. Example: Lead notification.
project_idintegerrequired- ID of the project the mail templates belong to. Use the id field returned by basin_list_projects. Example: 1024.
bodystring- Raw HTML of the email, up to 262144 bytes. A blank body is accepted. Basin sanitizes the HTML when the email is sent. Example: <p>New submission received</p>.
basin_create_projectCreate a new project to group forms.WriteCreate Project
Create a new project to group forms. Returns the project's id, name, created_at, and updated_at. Use basin_create_form with the returned id to add forms to it.
Inputs
namestringrequired- Name of the new project. Example: Marketing site.
basin_update_formChange settings on an existing form; only the fields you provide are changed.WriteUpdate Form
Change settings on an existing form; only the fields you provide are changed. Returns the form record: id, uuid, name, project_id and project_name, timezone, redirect_url, notification and autoreply settings, spam protection flags, retention_days, form_webhooks, and inbox, spam and trash counts. Use basin_get_form first to read the current settings. Use basin_create_form for a new form.
- Idempotent
Inputs
form_idstringrequired- ID of the form to update. Use the numeric id field returned by basin_list_forms. Example: 73320.
additional_settingsobject- Any other form attribute from Basin's API reference, as a JSON object merged into the form. Use it for settings that have no input above, such as redirect page text and colors (redirect_heading, redirect_message, button_background_color), mail templates (notification_mail_template_id, auto_response_mail_template_id), a custom sending domain (domain_id, domain_email), or use_ajax. Inputs above win over the same key here. Example: {"redirect_heading": "Thanks!", "button_background_color": "#24292E"}.
allowed_domainsarray- List of website domains allowed to submit to this form. Sending a list replaces the current one. Example: ["example.com", "www.example.com"].
autoreplyboolean- Set true to send an automatic reply email to the person who submitted the form, false to turn it off. Example: true.
autoreply_bodystring- Body text of the automatic reply sent to the submitter. Example: We received your message and will reply within one business day.
autoreply_from_namestring- Sender name shown on the automatic reply. Example: Acme Support.
autoreply_subjectstring- Subject line of the automatic reply sent to the submitter. Example: Thanks for contacting us.
blocked_domainsarray- List of domains whose submissions are blocked. Sending a list replaces the current one. Example: ["spam-domain.test"].
content_blacklistarray- List of words or phrases that mark a submission as spam when they appear in it. Sending a list replaces the current one. Example: ["casino", "crypto giveaway"].
duplicate_filterboolean- Set true to filter out duplicate submissions, false to accept them. Example: true.
force_hcaptchaboolean- Set true to require hCaptcha on submissions to this form. Example: false.
force_recaptchaboolean- Set true to require Google reCAPTCHA on submissions to this form. Example: false.
honeypot_fieldstring- Name of a hidden honeypot input in your HTML form. Submissions that fill it in are treated as spam. Example: _gotcha.
namestring- Name of the form as shown in the Basin dashboard. Example: Contact form. Leave out to keep the current name.
notification_bcc_emailsstring- Comma-separated list of 'bcc' recipients for notification emails. Sending a list replaces the current bcc recipients; leave out to keep them. New addresses must be verified. Example: archive@example.com.
notification_cc_emailsstring- Comma-separated list of 'cc' recipients for notification emails. Sending a list replaces the current cc recipients; leave out to keep them. New addresses must be verified. Example: manager@example.com.
notification_emailsstring- Comma-separated list of 'to' recipients for new-submission notification emails. Sending a list replaces the current recipients; leave out to keep them. Newly added addresses must be verified before they receive notifications. To remove all recipients, send {"notification_emails": ""} in additional_settings. Example: sales@example.com,ops@example.com.
notification_from_namestring- Sender name shown on notification emails. Example: Website Forms.
notification_subjectstring- Subject line of the notification email sent for each new submission. Example: New website lead.
project_idinteger- ID of the project the form belongs to. Use the id field returned by basin_list_projects. Example: 1024. Leave out to keep the current project.
redirect_urlstring- URL Basin redirects the visitor to after a successful submission. Example: https://example.com/thanks.
retention_daysinteger- Number of days Basin keeps submissions for this form before deleting them. Example: 90.
smtp_email_validationboolean- Set true to check submitted email addresses against their mail server before accepting the submission. Example: true.
timezonestring- Time zone used for the form's dates and date-range filters, as Basin stores it (for example the zone name shown in the form settings). Example: Eastern Time (US & Canada).
basin_update_mail_templateChange the name or HTML of an existing email template; only the fields you provide are changed.WriteUpdate Mail Template
Change the name or HTML of an existing email template; only the fields you provide are changed. Returns the mail template's id, name, project_id, body (the latest submitted HTML, or the approved HTML when nothing is pending), created_at, and updated_at. Use basin_get_mail_template to read the current HTML first.
- Idempotent
Inputs
mail_template_idintegerrequired- ID of the mail template to update. Use the id field returned by basin_list_mail_templates. Example: 512.
bodystring- Raw HTML of the email, up to 262144 bytes. A blank body is accepted. Basin sanitizes the HTML when the email is sent. Example: <p>New submission received</p>.
namestring- Name of the mail template, up to 100 characters. Example: Lead notification. Leave out to keep the current name.
basin_update_projectRename an existing project.WriteUpdate Project
Rename an existing project. Returns the project's id, name, created_at, and updated_at. Use basin_list_projects to find the ID.
- Idempotent
Inputs
namestringrequired- New name for the project. Example: Marketing site (2026).
project_idstringrequired- ID of the project to rename. Use the id field returned by basin_list_projects. Example: 1024.
basin_update_submissionMark a submission as read or unread, spam or not spam, or move it into or out of the trash.WriteUpdate Submission
Mark a submission as read or unread, spam or not spam, or move it into or out of the trash. Returns the submission: id, email, payload_params (the submitted field values), form_id, form name and uuid, spam, read and trash flags, spam_reason, ip, referrer, user_agent, attachments, webhook_sent_at, and timestamps. Use this to triage submissions. Use basin_delete_submission to remove one permanently. Provide at least one of read, spam, or trash.
- Idempotent
Inputs
submission_idintegerrequired- ID of the submission to update. Use the id field returned by basin_list_submissions. Example: 61109858.
readboolean- Set true to mark the submission as read, false for unread. Example: true.
spamboolean- Set true to mark the submission as spam, false to mark it as not spam. Example: false.
trashboolean- Set true to move the submission to the trash, false to restore it. Example: false.
basin_delete_formPermanently delete a form by its ID.DestructiveDelete Form
Permanently delete a form by its ID. Returns the deleted form record. Use basin_update_form to change a form instead of removing it.
- Idempotent
Inputs
form_idstringrequired- ID of the form to delete. Use the numeric id field returned by basin_list_forms. Example: 73320.
basin_delete_mail_templatePermanently delete an email template by its ID.DestructiveDelete Mail Template
Permanently delete an email template by its ID. Returns an empty response (HTTP 204) on success. Use basin_list_mail_templates to find the ID.
- Idempotent
Inputs
mail_template_idintegerrequired- ID of the mail template to delete. Use the id field returned by basin_list_mail_templates. Example: 512.
basin_delete_projectPermanently delete a project by its ID.DestructiveDelete Project
Permanently delete a project by its ID. Returns the deleted project's id, name, created_at, and updated_at. Use basin_update_project to rename a project instead.
- Idempotent
Inputs
project_idstringrequired- ID of the project to delete. Use the id field returned by basin_list_projects. Example: 1024.
basin_delete_submissionPermanently delete a form submission by its ID.DestructiveDelete Submission
Permanently delete a form submission by its ID. Returns Basin's confirmation of the deletion. Use basin_update_submission with trash set to true to move it to the trash instead.
- Idempotent
Inputs
submission_idintegerrequired- ID of the submission to delete. Use the id field returned by basin_list_submissions. Example: 61109858.
No tools match.
