Skip to main content
POST
/
agents
/
{agentId}
/
skills
Error
A valid request URL is required to generate request examples
{
  "success": true,
  "data": {
    "id": "<string>",
    "agentId": "<string>",
    "organizationId": "<string>",
    "name": "<string>",
    "description": "<string>",
    "parametersSchema": {},
    "requiredParams": [
      "<string>"
    ],
    "executionConfig": {},
    "dataEgressMap": {},
    "allowedFields": [
      "<string>"
    ],
    "isWrite": true,
    "requiresVerifiedIdentity": true,
    "requiresConfirmation": true,
    "nonParallelizable": true,
    "channels": [],
    "errorHandling": {},
    "isEnabled": true,
    "expectedLatencyMs": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "message": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Flowyte secret API key (Authorization: Bearer flowyte_sk_live_…). Scope-gated; is scoped to your organization — a key can never reach another tenant. The listed scopes in each operation's apiKey requirement are the scopes that key must hold. The tokenUrl is nominal: keys are minted in the dashboard.

Headers

​
Idempotency-Key
string

Client-supplied idempotency key on mutating POSTs (API-First).

Path Parameters

​
agentId
string
required

Body

application/json
​
name
string
required
​
description
string
required
​
skillType
enum<string>
required
Available options:
db_query,
http_webhook,
transfer,
sms,
email,
calendar,
google_sheets,
crm,
mcp,
playbook,
knowledge_query,
builtin,
geo,
native_graphql,
native_rest,
native_sql
​
parametersSchema
object

JSON Schema for the values the agent COLLECTS from the caller during the conversation. MUST be a JSON Schema object of the form { "type": "object", "properties": { "<param_name>": { "type": "string|number|boolean", "description": "..." }, ... }, "required": ["<param_name>", ...] } — an object with a top-level "properties" map, NOT a bare/flat map of param->spec. Put ONLY caller-collected inputs here; operator settings (e.g. an email skill's to/subject/from_name) belong in executionConfig, never here.

​
requiredParams
string[]
​
toolMode
enum<string>
Available options:
two_way,
one_way
​
executionConfig
object

Skill-type-specific operator settings (NOT the caller-collected values — those go in parametersSchema). Keys depend on skillType: email — { to: recipient email(s), comma-separated, REQUIRED, supports {param} templating e.g. "team@co.com" or "{customer_email}"; subject: REQUIRED, supports {param}; from_name: optional inbox display name (the address is always the verified no-reply@ sender, never set it here); intro: optional lead line; reply_to: optional, supports {param} e.g. "{customer_email}" }. http_webhook — { url (REQUIRED), method, headers, timeout_ms }. db_query — { sql_template }. transfer — { destination }. builtin — { action: end_call|take_message|repeat }. geo — { action: check_service_area|find_nearest_location; for check_service_area: origin_address + radius_miles (is the caller within radius_miles of origin_address?); for find_nearest_location: roster = an array of { label, address, phone, lat?, lng? } locations to find the closest of (pre-geocode a large roster via POST /agents/{id}/geocode-roster so lat/lng are stored and routing is instant), plus optional route_by_caller_number:true to route from the caller's inbound-number area code (approximate — confirmed with the caller) when no address is given, plus optional radius_miles to gate coverage (each location covers that many miles, so the result carries in_service_area=false and the agent says it doesn't serve the area when the nearest location is farther) }. The LLM passes the caller's { address }. Geo is FREE to customers. Native-integration skills (calendar/google_sheets/shopify) are configured via the connect/provision flow, not here.

​
dataEgressMap
object
​
allowedFields
string[]
​
isWrite
boolean
​
requiresVerifiedIdentity
boolean
​
requiresConfirmation
boolean
​
verificationLevel
enum<string>
Available options:
none,
basic,
step_up
​
nonParallelizable
boolean
​
channels
enum<string>[]

Open enum (future sms|whatsapp|email slot in with no schema change).

Available options:
voice,
chat
​
errorHandling
object
​
isEnabled
boolean
​
stakes
enum<string>

Per-skill confirmation-gate hint the voice runtime reads defensively. Default low.

Available options:
low,
medium,
high
​
availabilityWindow
enum<string>

Per-skill availability — both (default), open (business hours only), or closed (after hours only).

Available options:
both,
open,
closed

Response

Created skill.

​
success
boolean
required
​
data
object
required
​
message
string
​
errors
object[]