Agent Builder API
The agent builder is part of the Conversational Agents Beta and available on Professional, Scale and Enterprise.
The agent builder drafts a ready-to-review agent from a description of what it should do: a persona, instructions, 1-7 skills and suggested knowledge sources. You review and edit the draft, then create the agent from it.
GET /agent-builder/estimate → what a build costs
POST /agent-builder/generate → 202, starts a build job
GET /agent-builder/jobs/{job_id} → poll until succeeded / failed
POST /agent-builder/create → 201, creates the agent as an unpublished draft
GET /agent-builder/describe/estimate → optional: what a description draft costs
POST /agent-builder/describe → optional: 202, drafts the `notes` text for you
Base URL: https://api.sendseven.com/api/v1/automation. All endpoints need the scope automation:create. If AI features are turned off for the workspace, they return 403 with "code": "ai_disabled".
Cost
A build always runs on Advanced and is charged by the AI work it needs, typically about 12 to 18 AI credits. Creating the agent from a build is not charged. Failed or cancelled AI runs are not charged: a build that fails or is interrupted costs nothing.
GET /agent-builder/estimate
{
"credits": 12,
"price_euros": null,
"ai_credit_rate_euros": "0.01",
"billable": true,
"charged_on": "usage",
"usage_billed": true,
"credits_p50": 12.2,
"credits_p90": 17.7
}
| Field | Notes |
|---|---|
credits | Typical AI credits of one build (credits_p50, rounded). An estimate: the build is charged by the AI work it actually needs |
price_euros | Always null: a build has no fixed price. Your AI credits are billed at your plan's AI credit price (ai_credit_rate_euros) |
ai_credit_rate_euros | Your plan's price of one AI credit |
billable | Always true: builds are charged AI credits |
charged_on | usage: charged by the AI work of the build |
usage_billed | true: credits is an estimate, not a fixed price |
credits_p50 / credits_p90 | Typical credits of a build / what a large build may reach |
The charge appears under AI usage in Settings > Usage (see Billing & limits).
Start a build
POST /agent-builder/generate
{
"company_name": "Example Shoes",
"website_url": "https://www.example.com",
"goals": ["answer_questions", "orders_shipping", "human_handoff"],
"tone": "friendly",
"base_language": "en",
"language_mode": "auto",
"channel_ids": ["CHANNEL_ID"],
"notes": "Answer questions about our shoes, sizes and orders. Free returns within 30 days. We do not ship outside the EU. Hand off to the team for complaints.",
"existing_prompt": null,
"ui_language": "en",
"request_id": "build-2026-10-05-001"
}
| Field | Notes |
|---|---|
company_name | Required. 1-120 characters. |
website_url | Optional, max 510. Its domain scopes the web research. The builder also reads up to 3 public pages of that website (for example the entered page and the homepage) to look for live data. Nothing else on the website is crawled. |
goals | Optional, 0-6 of answer_questions, qualify_leads, support, orders_shipping, collect_feedback, human_handoff. Duplicates are removed. Missing or null counts as none. |
other_goal | Optional, max 200 characters after trimming. A goal in your own words that the list does not cover, for example "Book demo calls". Empty counts as not sent. |
tone | friendly, professional, casual, formal or enthusiastic. |
base_language | Required. The agent's base language as a BCP-47 code, max 10 characters. Codes are normalised, so pt_br becomes pt-BR. |
language_mode | auto (default) = the agent answers in the contact's language. fixed = the agent always answers in base_language. |
languages | Deprecated. Older clients may still send a list of 1-5 codes. If base_language is missing, languages[0] becomes the base language with mode auto. If you send both, base_language wins. |
channel_ids | 0-20 channels the agent is meant for. An unknown channel returns 422 invalid_channel. |
notes | Required. What the agent should do: its tasks, the facts and rules it must follow, what to ask the customer for and when to hand off. 50-8,000 characters after trimming; shorter or missing returns 422 ("Describe what your agent should do (at least 50 characters)."). Draft a description can write it for you. |
existing_prompt | Optional, max 20,000 characters after trimming. An existing prompt or script you want the agent to build on. It is used as reference material only; an empty value counts as not sent. |
ui_language | Optional, max 16. The language of the draft's skills, warnings and research notes. Defaults to base_language. |
request_id | Optional, 8-64 characters A-Z a-z 0-9 _ . : -. Sending the same request_id again returns the existing job instead of starting a new build; a replay does not count against the build limits and is never charged again. |
Unknown fields are rejected (422). A request with neither base_language nor a non-empty languages also returns 422.
The response is 202 Accepted with the job (see below).
Build limits
| Limit | Value |
|---|---|
| Builds per workspace | 5 per hour, 20 per day |
| Builds running at the same time | 1 per workspace (409 build_in_progress) |
Draft a description
Optional. If you do not want to write notes yourself, the builder can draft it from the company, its website, the goals and anything you already wrote. Nothing is saved: you get a text back, review or edit it, and send it as notes to /generate.
GET /agent-builder/describe/estimate has the same fields as the build estimate. A description draft always runs on Advanced and typically uses about 6 AI credits (credits_p90 about 11 for a long text). It is charged by the AI work it does; a failed draft costs nothing.
POST /agent-builder/describe
{
"company_name": "Example Shoes",
"website_url": "https://www.example.com",
"goals": ["answer_questions"],
"other_goal": "Book fitting appointments",
"tone": "friendly",
"base_language": "en",
"language_mode": "auto",
"channel_ids": ["CHANNEL_ID"],
"notes": "Free returns within 30 days.",
"existing_prompt": null,
"ui_language": "en",
"request_id": "describe-2026-11-02-001"
}
The fields are those of /generate with these differences: goals may be empty, tone is optional, notes is optional (max 8,000, no minimum; the draft builds on it), and there is no languages. existing_prompt (optional, max 20,000 characters after trimming) is an existing prompt or script, for example from another chatbot tool. The draft translates it into a SendSeven description: tool-specific syntax such as template variables or function-call formats is left out, and anything SendSeven cannot do the same way is listed in warnings. Unknown fields are rejected (422).
The response is 202 Accepted with a job; poll it with GET /agent-builder/jobs/{job_id}. A description job has "kind": "describe" and, when succeeded, a result of:
{
"description": "Example Shoes sells running and trail shoes online …",
"sources": [{"url": "https://www.example.com/about", "title": "About us"}],
"warnings": []
}
description is the suggested notes text (max 8,000 characters), sources the website pages it was based on, and warnings notes such as a website that could not be read. Like a build, the job has usage_billed and credits_charged. A description job cannot be used with /create.
| Limit | Value |
|---|---|
| Description drafts per workspace | 10 per hour, 30 per day (429 rate_limit_exceeded) |
| Drafts running at the same time | 1 per workspace (409 describe_in_progress). Independent of builds: you can draft a description while a build runs. |
The same request_id returns the existing job and is never charged again. In a free trial a draft uses trial AI credits like any AI feature; when they are used up the call returns 403 trial_ai_credits_exhausted.
Poll the job
GET /agent-builder/jobs/{job_id}
{
"job_id": "…",
"status": "running",
"stage": "drafting",
"result": null,
"error": null,
"usage_billed": true,
"credits_charged": null,
"request_id": "build-2026-10-05-001",
"created_at": "2026-10-05T09:00:00Z",
"updated_at": "2026-10-05T09:00:20Z"
}
| Field | Notes |
|---|---|
kind | build for a build, describe for a description draft |
status | queued, running, succeeded or failed |
stage | While running: researching, drafting or checking |
result | When succeeded: the draft with build_id, agent, skills, knowledge_sources, live_sources, data_mapping, research, warnings and credits_charged. data_mapping holds the contact fields and tags the agent uses (missing on drafts from older builds). result.agent includes base_language and language_mode. live_sources holds the proposed live sources and may be empty. credits_charged is the AI credits the build used (may have decimals; 0 for a free trial build) and null in the rare case the charge could not be confirmed. |
error | When failed: {code, message, credits_charged}. Failed or cancelled AI runs are not charged: a build that stops with invalid_request, ai_unavailable, ai_error or interrupted reports credits_charged 0 at the top level. failed_after_charge means the draft was generated and charged (credits_charged: the AI credits of the build, may have decimals, e.g. 13.47) but could not be saved; contact support. charge_unknown means the build was interrupted and the charge could not be checked yet; poll again. |
usage_billed | true: the build is charged by the AI work it did, whatever its outcome |
credits_charged | AI credits of a successful build (may have decimals, e.g. 13.214; 0 for a free trial build). 0 for a failed build, because failed or cancelled AI runs are not charged (except failed_after_charge, which shows the charged credits). null while the build runs or when the charge is not known yet; poll again |
The job status always follows the recorded charge. If a build was charged but its job was interrupted before it was marked as finished, the next poll (or a replay with the same request_id) returns it as succeeded with the saved draft and its credits_charged (for example 13.47), so you can still create the agent. A build is never charged twice.
Proposed live sources
If the website has pages with current, structured data, result.live_sources proposes up to 5 live sources. The agent reads these pages while it answers instead of relying on a copy in the Knowledge Base.
"live_sources": [
{
"url": "https://www.example.com/events",
"match": "exact",
"label": "Events calendar",
"description": "Current events from example.com with dates, times, places and links. …",
"ttl_minutes": 60,
"fetcher": "auto",
"scope": "skills",
"skill_slugs": ["example-events"],
"kind": "events",
"live_mode": "always"
}
]
kind | Found on the page | Proposal |
|---|---|---|
events | An events calendar (at least 3 events) | Bound to the matching skill (scope: "skills"). That skill reads it on every reply (live_mode: "always"). Cached for 60 minutes. |
products | A product or price list (at least 3 items) | Bound to the matching skill. The skill reads it when needed (live_mode: "model"). Cached for 60 minutes. Products are never presented as in stock: the description tells the agent that the page is no stock or availability guarantee. |
opening_hours | Opening hours | Available to the whole agent (scope: "agent"). Cached for 12 hours. |
If no draft skill fits, a proposal uses scope: "agent". kind and live_mode are informational: you don't need to send them back.
Proposals are never created automatically. Send the ones you want in live_sources when you create the agent. Reading the pages is part of the build and costs nothing extra.
Contact fields and tags
The builder knows your workspace's custom contact fields and tags. It uses your custom contact fields only if your token or role also has custom_fields:read, and your tags only with contacts:read or conversations:read; otherwise the draft proposes new ones without seeing what exists. result.data_mapping lists the ones the agent should collect or apply, and proposes new ones where nothing fits:
"data_mapping": {
"fields": [
{"key": "order_number", "label": "Order number", "type": "text", "options": null,
"status": "existing", "ai_writable": true, "purpose": "To look up the order."},
{"key": "shoe_size", "label": "Shoe size", "type": "select", "options": ["38", "39", "40"],
"status": "proposed", "ai_writable": true, "purpose": "To recommend the right size."}
],
"tags": [
{"name": "Support", "tag_id": "TAG_ID", "status": "existing", "hint": "Any support request."},
{"name": "Complaint", "tag_id": null, "status": "proposed", "hint": "The customer is unhappy."}
]
}
| Field | Notes |
|---|---|
fields[] | Up to 10. key, label, type (text, number, boolean, date, select, multiselect, email, phone, url), options (select types only), status, ai_writable, purpose. |
fields[].status | existing: a custom field of your workspace. proposed: a new field, created only if you confirm it. |
fields[].ai_writable | Whether the agent may fill the field. An existing field keeps its AI access; the builder never changes it. A proposed field is created with AI access fill_if_empty. |
tags[] | Up to 8. name, tag_id (existing tags only), status (existing or proposed), hint (when the agent applies the tag on handoff). |
Standard contact fields (name, email, phone and so on) never appear as proposals: the agent sees them as read-only context.
Nothing is created while the build runs. To create proposed fields or tags, list them in confirmed_new_fields / confirmed_new_tags when you create the agent.
A build typically takes 40-60 seconds. Poll every few seconds until status is succeeded or failed. An unknown job returns 404 job_not_found.
Create the agent
Send the draft back, edited as you like, to POST /agent-builder/create:
{
"build_id": "…",
"agent": {
"name": "Example Shoes Assistant",
"persona": "…",
"instructions": "…",
"base_language": "en",
"language_mode": "auto",
"tools_config": {"search_knowledge": true, "handoff": true, "set_state": true},
"handoff_config": {"keywords": ["human", "agent"]},
"escalation_enabled": true
},
"skills": [
{"key": "returns", "title": "Returns", "description": "Use when the customer wants to return an item.", "mode": "model_selected", "body": "…"}
],
"knowledge_sources": [{"source_type": "kb_all"}],
"channel_ids": ["CHANNEL_ID"],
"confirmed_new_fields": ["shoe_size"],
"confirmed_new_tags": ["Complaint"]
}
| Field | Notes |
|---|---|
build_id | Required. From the job result. |
agent | name (required), persona (max 15,000), instructions, model_tier, base_language, language_mode, tools_config, handoff_config, escalation_enabled. Same rules as creating an agent. Drafts from older builds may carry default_language / supported_languages instead; these are still accepted, and the first language becomes base_language with mode auto. |
skills | Required. 1-7 skills. key matches the draft skill; slug optional; title, description, body required; mode is the link mode. Remove skills you don't want. |
knowledge_sources | Up to 20: {source_type: kb_folder | kb_all | web_search | faq, kb_folder_id?, allowed_domains?, is_enabled?}. |
live_sources | Optional, up to 5. The proposed live sources you want to keep, edited as you like: {url, match?, label, description?, ttl_minutes?, fetcher?, scope?, skill_slugs?}. The rules are the same as for live sources on an agent. Leave it out or send [] to create none. |
channel_ids | Channels the agent answers on once you publish it. |
confirmed_new_fields | Optional, up to 10 keys of proposed fields in the build's data_mapping to create. Leave it out or send [] to create none. |
confirmed_new_tags | Optional, up to 8 names of proposed tags in the build's data_mapping to create. Leave it out or send [] to create none. |
confirmed_goal_skills | Optional, up to 7 skill keys. The draft skills whose suggested skill goal you want to keep (at most 3 are used). Leave it out or send [] to create no goals. |
The language choice is stored on the agent's language_settings:
language_mode | language_detection_strategy | response_language |
|---|---|---|
auto | cascade | null (answer in the contact's language) |
fixed | fixed | the base_language |
The response is 201 with the agent, exactly as GET /agents/{agent_id} returns it. The agent is created as an unpublished draft that is switched on (publish_state: "draft", is_active: true). It answers only in the test console until you publish it with POST /agents/{agent_id}/publish, which needs automation:publish. A caller without automation:publish gets the draft paused (is_active: false).
Each live source becomes a live_source knowledge source. For each skill in its skill_slugs, the agent's skill link gets sources: {"web_search_mode": null, "live_source_ids": [...], "live_mode": "…"}. The live_mode is always for an events calendar and model otherwise. Slugs of skills you removed are ignored. If none of the slugs is left, the live source falls back to scope: "agent". If any live source is invalid, nothing is created.
How the data mapping is applied
- The field and tag definitions always come from the stored build, never from your request. A key or name that is not a
proposedentry of the build is ignored. - A confirmed field is created with AI access
fill_if_empty(the agent may fill it once but never overwrites a value). If a field with that key exists by now, it is reused as it is. Creating a field needs the scopecustom_fields:create. - A confirmed tag reuses an existing tag with the same name (not case-sensitive); otherwise it is created. If the same tag is created elsewhere at the same moment, that tag is reused. Creating a tag needs the scope
tags:create. Without the scope the call returns403 missing_scopeand nothing is created. - The agent's contact context (
settings.context) lists the mapped fields:custom_field_keysin thecontact_profileprovider for reading,writable_custom_field_keysfor the fields whose AI access lets the agent fill them, including the new ones. - All mapped tags are added to
handoff_config.handoff_tag_ids, with their hint inhandoff_tag_hintsunless you sent your own hint for that tag. - Existing fields or tags that were deleted since the build are skipped. Drafts without
data_mapping(older builds) are created exactly as before.
Skill goals
When the description says what to collect before handing over (or how to tag), a tailored draft skill may carry a suggested goal (at most 3 skills, never the foundation skill). It refers to entries of the build's data_mapping:
{
"objective": "Qualify the lead, then hand over to sales.",
"outputs": [{"field_ref": "budget", "required": true}],
"after": "handoff",
"fixed_tags": [{"name": "Lead"}],
"fixed_tags_target": "conversation",
"choose_tag": {"tags": [{"tag_id": "TAG_ID_HOT"}, {"name": "Warm"}], "max": 1, "required": true, "target": "contact", "hints": {"Warm": "Interested, no date yet"}}
}
A goal is created only for the skills you list in confirmed_goal_skills, and always from the stored build. On create, field_ref becomes the contact field: an existing one whose AI access lets the agent write it (read_write or fill_if_empty), one you confirmed in confirmed_new_fields, or a standard field such as email. An existing field set to none or read is never used by a goal (output_skipped) and each tag becomes an existing tag or one you confirmed in confirmed_new_tags. Anything you did not confirm is left out. If fewer than 2 tags are left to choose from, the choice is left out; if a goal has no fields and no tags left, it is not created. The goal saves its answers to the contact, adds the fixed tags, lets the agent choose a tag, puts both on the target the draft suggests (fixed_tags_target, choose_tag.target; anything other than contact or both means the conversation) and hands off when after is handoff. Its webhook is off; turn it on in the skill if you need it.
What happened is stored on the agent in settings.builder_goals: created (skill keys that got a goal) and notes ({skill_key, code} with output_skipped, tag_skipped, tag_choice_skipped, goal_skipped, goal_invalid or goal_unavailable).
Fields, tags, goals and the agent are created together: if anything fails, nothing is created.
Creating is idempotent per build_id: repeating the call returns the same agent. Builds expire after a while; an expired build_id returns 404 build_not_found, so create the agent soon after the build succeeds.
Errors
Builder errors use {"detail": {"code": "…", "error": "…", "message": "…"}}; error repeats code. The per-agent live-source checks (live_source_limit, live_source_label_taken, invalid_live_source_url) are shared with the Agents API and return {"detail": {"code": "…", "message": "…"}} without error; invalid_live_source_url also has error_code. Always read detail.code. The general shapes are described in Error handling.
| Status | code | When |
|---|---|---|
402 | trial_ai_generation_limit_reached | Free trial only: the trial's free builds are used up and the remaining trial AI credits do not cover another build. Checked before the build starts. The body has kind (agent), limit, used, credits_required, credits_remaining, free_generations_limit, free_generations_used and upgrade_url. See Free trial limits. |
403 | feature_disabled | The plan does not include Conversational Agents or AI features |
403 | ai_disabled | AI features are turned off for the workspace |
403 | trial_ai_credits_exhausted | Free trial only, /describe: the trial AI credits are used up |
403 | missing_scope | Creating a confirmed field needs custom_fields:create, creating a confirmed tag needs tags:create |
404 | job_not_found | Unknown job_id |
404 | build_not_found | Unknown build_id |
409 | build_in_progress | Another build is running |
409 | describe_in_progress | Another description draft is running |
409 | build_not_ready | The build has not succeeded yet |
409 | create_in_progress | The same build is being created right now |
422 | build_failed | The build failed; start a new one |
422 | invalid_channel | A channel id is unknown |
422 | invalid_request | The draft is invalid (for example a skill or knowledge source) |
422 | invalid_live_source | A live source in live_sources is invalid |
422 | live_source_limit | Too many live sources for one agent |
422 | live_source_label_taken | Two live sources have the same label |
422 | invalid_live_source_url | A live source URL cannot be used (for example a private address) |
429 | rate_limit_exceeded | Build or description limit reached. The body has retry_after (seconds) and the Retry-After header is set. |
503 | ai_unavailable | The AI service or the job queue is temporarily unavailable. Retry after 30 seconds (Retry-After: 30). |
Complete example
API=https://api.sendseven.com/api/v1/automation
AUTH="Authorization: Bearer $SENDSEVEN_API_TOKEN"
# 1. Start the build
JOB=$(curl -s -X POST "$API/agent-builder/generate" -H "$AUTH" -H "Content-Type: application/json" \
-d '{"company_name":"Example Shoes","goals":["answer_questions","human_handoff"],"tone":"friendly","base_language":"en","notes":"Answer questions about our shoes and orders. Hand off to the team for complaints.","request_id":"example-build-0001"}' \
| jq -r .job_id)
# 2. Wait for it
while true; do
STATUS=$(curl -s "$API/agent-builder/jobs/$JOB" -H "$AUTH" | tee job.json | jq -r .status)
[ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ] && break
sleep 3
done
# 3. Create the agent from the unedited draft
jq '{build_id: .result.build_id, agent: .result.agent, skills: .result.skills, knowledge_sources: .result.knowledge_sources}' job.json \
| curl -s -X POST "$API/agent-builder/create" -H "$AUTH" -H "Content-Type: application/json" -d @-