> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowyte.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a skill > Adds a new skill to an agent so it can perform an action, such as sending an email or booking an appointment, during conversations. Publish the agent for the new skill to take effect on live calls and chats. ## OpenAPI ````yaml /openapi.yaml post /agents/{agentId}/skills openapi: 3.1.0 info: title: Flowyte V2 Control-Plane REST API version: 1.0.0 description: >- The single REST API for the Flowyte platform (base path `/api/v1`). Authenticate every request with a secret API key — `Authorization: Bearer flowyte_sk_…` — and each operation lists the scope the key must hold. Successful responses use the `ApiResponse` envelope; list responses use cursor-based `PaginatedResponse`. Errors are RFC 9457 problem+json. Streaming endpoints return Server-Sent Events (`event:\ndata:\n\n`, terminating with `event: done`). contact: name: Flowyte Platform license: name: Proprietary servers: - url: /api/v1 description: Flowyte control-plane (versioned URI; additive in v1). security: - apiKey: [] tags: - name: Agents description: The single user-facing entity. - name: Skills description: > Agent capabilities / tools. A skill is ONE atomic action — typically a single API call the agent makes in one step (look up an order, create a record, send a message, transfer the call). Use a skill when the task is a single step. When a task needs several details gathered across turns BEFORE acting, build a Playbook (which gathers the inputs and then calls skills) — see the Playbooks tag. - name: Integrations description: Native OAuth integrations. - name: Knowledge description: RAG knowledge sources & preview. - name: Playbooks description: > Multi-turn conversation scripts — a node graph (gather → confirm → branch) the agent follows to collect several inputs IN ORDER across turns before acting. Build a playbook when a single skill call isn't enough because the agent must gather MANY details first, or run a SEQUENCE of skills, before it can finish (e.g. take a full service request: gather the problem, address, and time, confirm, THEN file it; qualify a lead; a multi-step intake). A playbook does NOT call an integration itself — it owns the conversation and holds the state across turns; the actual action is performed by the SKILL(s) it gathers the inputs for. So a playbook ORCHESTRATES skills. Rule of thumb — one API call → a Skill; "gather N things in order, then submit" → a Playbook that drives the conversation and calls the skill(s) at the end. - name: Variables description: > The agent-wide interaction-variable registry (B.4b) — DERIVED at read time from the agent's playbooks and skills (collect slots, skill output bindings, {var} placeholders) and merged with a thin annotation overlay (notes, declared type hints, manual declarations). Read-only observation, NEVER a gate: it never validates a reference and never affects authoring, publish, or runtime behaviour. - name: Guardrails description: Deterministic guardrail policies & caller verification. - name: Numbers description: Phone numbers / DIDs. - name: Test description: Test, simulate, talk-token, probe. - name: Observe description: Post-call analytics, conversations, receipts, transcripts. - name: Billing description: Plans, wallet, usage, fixed phrases. - name: Voices description: Voice catalog. - name: Webhooks description: Webhook endpoints & deliveries. - name: AuditLogs description: API/key activity logs. - name: Chat description: Chat channel — sessions, messages, OpenAI-compatible, widget. - name: PublishableKeys description: Browser-safe, one-agent publishable keys. - name: Widget description: Embed widget config + snippet. - name: Uploads description: Multipart file uploads backing file_id params - name: Meta description: Platform metadata (language/SKU/tier capabilities). paths: /agents/{agentId}/skills: parameters: - $ref: '#/components/parameters/AgentIdPathScoped' post: tags: - Skills summary: Create a skill description: >- Adds a new skill to an agent so it can perform an action, such as sending an email or booking an appointment, during conversations. Publish the agent for the new skill to take effect on live calls and chats. operationId: createSkill parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SkillCreate' responses: '201': description: Created skill. content: application/json: schema: $ref: '#/components/schemas/ApiResponse_Skill' '400': $ref: '#/components/responses/ValidationError' '404': $ref: '#/components/responses/NotFound' security: - apiKey: - skills:write components: parameters: AgentIdPathScoped: name: agentId in: path required: true schema: type: string IdempotencyKey: name: Idempotency-Key in: header description: Client-supplied idempotency key on mutating POSTs (API-First). schema: type: string schemas: SkillCreate: type: object required: - name - description - skillType properties: name: type: string description: type: string skillType: $ref: '#/components/schemas/SkillType_enum' parametersSchema: type: object additionalProperties: true description: >- 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": { "": { "type": "string|number|boolean", "description": "..." }, ... }, "required": ["", ...] } — 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: type: array items: type: string toolMode: type: string enum: - two_way - one_way executionConfig: type: object additionalProperties: true description: >- 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: type: object additionalProperties: type: string allowedFields: type: array items: type: string isWrite: type: boolean requiresVerifiedIdentity: type: boolean requiresConfirmation: type: boolean verificationLevel: $ref: '#/components/schemas/VerificationLevel' nonParallelizable: type: boolean channels: type: array items: $ref: '#/components/schemas/Channel' errorHandling: type: object additionalProperties: true isEnabled: type: boolean stakes: type: string enum: - low - medium - high description: >- Per-skill confirmation-gate hint the voice runtime reads defensively. Default low. availabilityWindow: type: string enum: - both - open - closed description: >- Per-skill availability — both (default), open (business hours only), or closed (after hours only). ApiResponse_Skill: allOf: - $ref: '#/components/schemas/ApiResponseBase' - type: object required: - data properties: data: $ref: '#/components/schemas/Skill' SkillType_enum: type: string enum: - db_query - http_webhook - transfer - sms - email - calendar - google_sheets - crm - mcp - playbook - knowledge_query - builtin - geo - native_graphql - native_rest - native_sql VerificationLevel: type: string enum: - none - basic - step_up Channel: type: string enum: - voice - chat description: Open enum (future sms|whatsapp|email slot in with no schema change). ApiResponseBase: type: object required: - success properties: success: type: boolean message: type: string errors: type: array items: type: object required: - field - message properties: field: type: string message: type: string Skill: type: object required: - id - agentId - organizationId - name - description - skillType properties: id: type: string agentId: type: string organizationId: type: string name: type: string description: type: string skillType: $ref: '#/components/schemas/SkillType_enum' parametersSchema: type: object additionalProperties: true requiredParams: type: array items: type: string toolMode: type: string enum: - two_way - one_way executionConfig: type: object additionalProperties: true description: >- 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: type: object additionalProperties: type: string allowedFields: type: array items: type: string isWrite: type: boolean requiresVerifiedIdentity: type: boolean requiresConfirmation: type: boolean verificationLevel: $ref: '#/components/schemas/VerificationLevel' nonParallelizable: type: boolean channels: type: array items: $ref: '#/components/schemas/Channel' errorHandling: type: object additionalProperties: true isEnabled: type: boolean stakes: type: string enum: - low - medium - high description: >- Per-skill confirmation-gate hint the voice runtime reads defensively. Default low. availabilityWindow: type: string enum: - both - open - closed description: >- Per-skill availability by the agent's business-hours window — both (default, around the clock), open (business hours only), or closed (after hours only). The runtime drops this skill's tool when the verdict excludes the window. expectedLatencyMs: type: integer readOnly: true description: >- Learned average response time of this skill in milliseconds (an EWMA over recent real calls). Read-only; omitted until the skill has at least one call. Shown as a per-skill stat in the builder and used by the runtime to pace the spoken acknowledgment. createdAt: type: string format: date-time updatedAt: type: string format: date-time ProblemDetails: description: RFC 9457 problem+json. type: object properties: type: type: string format: uri default: about:blank title: type: string status: type: integer detail: type: string instance: type: string code: type: string errors: type: array items: type: object properties: field: type: string message: type: string ApiResponse_Void: allOf: - $ref: '#/components/schemas/ApiResponseBase' - type: object properties: data: type: - object - 'null' responses: ValidationError: description: Validation failure (errors[] populated on the envelope). content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ApiResponse_Void' NotFound: description: Resource not found in org scope. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' securitySchemes: apiKey: type: oauth2 description: > 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. flows: clientCredentials: tokenUrl: /api/v1/api-keys scopes: agents:read: Read agents. agents:write: Create/update/delete agents, publish, rollback. knowledge:read: Read knowledge sources & preview. knowledge:write: Add/remove knowledge sources, uploads. skills:read: Read skills & skill-types. skills:write: Create/update/delete skills. playbooks:read: Read playbooks & graphs. playbooks:write: Create/update/delete playbooks & graphs. guardrails:read: Read guardrail policies & caller-verification. guardrails:write: Update guardrail policies & caller-verification. numbers:read: Read phone numbers / search availability. numbers:write: Purchase / assign / release numbers. sms:read: Read the org's SMS (10DLC) registration status and numbers. sms:write: Save/submit the 10DLC registration and toggle numbers for SMS. outbound:read: Read outbound contact lists and campaigns. outbound:write: >- Create/import contact lists, create/launch/pause/resume/cancel outbound campaigns, and enqueue single outbound calls. integrations:read: Read connected native integrations (status only — never tokens). integrations:write: Discover schemas, set data scoping, and disconnect a connection. integrations:connect: >- Connect a data source (submit credentials / begin OAuth) — a SEPARATE, higher-privilege scope because connecting INGESTS credentials and opens a new egress path; a discover/scope/author key need not carry it. calls:read: Read conversations, receipts, transcripts, analytics. analytics:read: >- Read the Observe history list, per-agent analytics (the answer-rate summary), and the raw knowledge-gap list. analytics:write: >- Curate knowledge gaps (dismiss / mark in-progress). [M4 — reserved] billing:read: Read plans, wallet, usage. audit:read: Read API/key activity logs. webhooks:write: Manage webhook endpoints. keys:write: Manage secret API keys. chat:read: Read chat sessions & messages. chat:write: Create chat sessions & send messages (server-side). widgets:read: Read widget config & embed snippet. widgets:write: Update widget config. pubkeys:read: Read publishable keys. pubkeys:write: Manage publishable keys. ````