Agent Builder API

Beta

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 short brief: 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 (inactive) agent

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 successful build costs 100 AI credits. Failed builds and creating the agent are free.

GET /agent-builder/estimate

{
  "credits": 100,
  "price_euros": "1.00",
  "ai_credit_rate_euros": "0.01",
  "billable": true,
  "charged_on": "successful_build"
}

Field	Notes
`credits`	AI credits charged for one successful build
`price_euros`	`credits` × your plan's AI credit price
`ai_credit_rate_euros`	Your plan's price of one AI credit
`billable`	`false` when builds are currently free

The charge appears in your usage as agent_builder (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": "Free returns within 30 days. We do not ship outside the EU.",
  "ui_language": "en",
  "request_id": "build-2026-10-05-001"
}

Field	Notes
`company_name`	Required. 1-120 characters.
`website_url`	Optional, max 510. Only its domain is used, as context. The website is not fetched.
`goals`	Required. 1-6 of `answer_questions`, `qualify_leads`, `support`, `orders_shipping`, `collect_feedback`, `human_handoff`.
`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`	Optional, max 2,000. Facts and rules the agent must follow.
`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`)

Poll the job

GET /agent-builder/jobs/{job_id}

{
  "job_id": "…",
  "status": "running",
  "stage": "drafting",
  "result": null,
  "error": null,
  "request_id": "build-2026-10-05-001",
  "created_at": "2026-10-05T09:00:00Z",
  "updated_at": "2026-10-05T09:00:20Z"
}

Field	Notes
`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`, `research`, `warnings` and `credits_charged`. `result.agent` includes `base_language` and `language_mode`.
`error`	When `failed`: `{code, message}` with `code` `invalid_request`, `ai_unavailable`, `ai_error` or `interrupted`. Nothing is charged.

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"]
}

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?}`.
`channel_ids`	Channels to activate the agent on once you switch it on.

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 inactive: test it in the test console, then activate it with PATCH /agents/{agent_id} {"is_active": true}.

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

All errors use {"detail": {"code": "…", "error": "…", "message": "…"}}; error repeats code.

Status	`code`	When
`403`	`feature_disabled`	The plan does not include Conversational Agents or AI features
`403`	`ai_disabled`	AI features are turned off for the workspace
`404`	`job_not_found`	Unknown `job_id`
`404`	`build_not_found`	Unknown `build_id`
`409`	`build_in_progress`	Another build 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)
`429`	`rate_limit_exceeded`	Build 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"],"base_language":"en","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 @-

Cost​

Start a build​

Build limits​

Poll the job​

Create the agent​

Errors​

Complete example​