> ## Documentation Index > Fetch the complete documentation index at: https://docs.akapulu.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Scenario > Create a scenario. Optionally mint hosted links in the same request. Create a scenario from [scenario JSON](/guides/scenarios/using-json). You can mint [hosted links](/guides/scenarios/hosted-links) in the same request. Required headers: * `Authorization: Bearer ` * `Content-Type: application/json` Required request fields: * `name` * `nodes_json` with `initial_node` and `nodes` Optional request fields: * `llm_model` (defaults to `gpt-4.1-mini`; full-size models require a paid plan) * `hosted_links` — each link needs `avatar_id` and a `runtime_vars` key for every `{{runtime.*}}` variable the scenario references (blank values are allowed) The response `hosted_links` array includes the public `url` (`https://live.akapulu.com/session/`). ## OpenAPI ````yaml openapi/akapulu.json POST /scenarios/create openapi: 3.1.0 info: title: Akapulu Labs API version: 1.0.0 description: Public Akapulu Labs API reference. servers: - url: https://akapulu.com/api security: - bearerAuth: [] paths: /scenarios/create: post: tags: - Scenarios summary: Create scenario description: Create a scenario. Optionally mint hosted links in the same request. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateScenarioRequest' examples: default: value: name: Sales Qualification llm_model: gpt-4.1-mini nodes_json: initial_node: intro role_instruction: >- You are a friendly sales assistant. Keep responses concise because they will be converted to audio. nodes: intro: task_instruction: >- Greet {{runtime.user_name}} from {{runtime.company_name}} and ask what they want to build. respond_immediately: true functions: - name: go_end description: End the conversation when the visitor is done. type: transition transition_to: end end: task_instruction: Thank them and say goodbye. end_after_bot_response: true hosted_links: - avatar_id: 66666666-7777-8888-9999-000000000000 label: Acme demo runtime_vars: user_name: Alex company_name: Acme Corp stt_keywords: - Acme record_conversation: false redirect_url: https://your-site.com/thanks responses: '200': description: Scenario created successfully content: application/json: schema: $ref: '#/components/schemas/ScenarioMutationResponse' examples: success: value: status: created id: 11111111-2222-3333-4444-555555555555 hosted_links: - id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee token: abc123token url: https://live.akapulu.com/session/abc123token label: Acme demo scenario_id: 11111111-2222-3333-4444-555555555555 avatar_id: 66666666-7777-8888-9999-000000000000 runtime_vars: user_name: Alex company_name: Acme Corp stt_keywords: - Acme record_conversation: false redirect_url: https://your-site.com/thanks created_at: '2026-08-16T21:47:46.000000+00:00' '400': description: Invalid request payload content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: default: value: error: name is required '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: invalid_key: value: error: Invalid API key components: schemas: CreateScenarioRequest: type: object required: - name - nodes_json properties: name: type: string nodes_json: $ref: '#/components/schemas/NodesJson' llm_model: $ref: '#/components/schemas/LlmModel' hosted_links: type: array items: $ref: '#/components/schemas/HostedLinkWrite' description: Optional hosted links to create with the scenario. ScenarioMutationResponse: type: object required: - status - id - hosted_links properties: status: type: string id: type: string format: uuid hosted_links: type: array items: $ref: '#/components/schemas/HostedLink' redirect_url: type: string description: Dashboard path. Ignore for API clients. ApiError: type: object required: - error properties: error: type: string description: Human-readable error message. NodesJson: type: object description: Scenario flow JSON. See the Using JSON guide for the full contract. additionalProperties: true properties: initial_node: type: string role_instruction: type: string nodes: type: object additionalProperties: true LlmModel: type: string description: >- OpenAI chat model for this scenario. Defaults to gpt-4.1-mini. Full-size models require a paid plan. enum: - gpt-4.1-nano - gpt-4.1-mini - gpt-4.1 - gpt-5.4-nano - gpt-5.4-mini - gpt-5.4 HostedLinkWrite: type: object required: - avatar_id properties: id: type: string format: uuid description: >- Existing hosted link ID. Required to keep/update a link on scenario update. Omit to create a new link. avatar_id: type: string format: uuid label: type: string maxLength: 255 runtime_vars: type: object additionalProperties: true description: >- Must include a key for every {{runtime.*}} variable the scenario references. Blank values are allowed. stt_keywords: type: array items: type: string maxItems: 5 record_conversation: type: boolean default: false redirect_url: type: string description: Optional http(s) URL to send the visitor after the call ends. HostedLink: type: object required: - id - token - url - label - scenario_id - avatar_id - runtime_vars - stt_keywords - record_conversation - redirect_url - created_at properties: id: type: string format: uuid token: type: string url: type: string description: >- Public hosted-link URL, for example https://live.akapulu.com/session/. label: type: string scenario_id: type: string format: uuid avatar_id: type: string format: uuid runtime_vars: type: object additionalProperties: true stt_keywords: type: array items: type: string record_conversation: type: boolean redirect_url: type: string created_at: type: string securitySchemes: bearerAuth: type: http scheme: bearer ````