> ## Documentation Index > Fetch the complete documentation index at: https://docs.starleads.co/llms.txt > Use this file to discover all available pages before exploring further. # Start a simulation chat with an agent > Starts a new text conversation with the agent and returns its identifier, the messages so far (the agent's welcome message, if any) and the agent definition. The agent must belong to the same company as the API key. Use `toolMocking` to keep the agent's tools from triggering real actions on your systems during the chat. ## OpenAPI ````yaml POST /SimulationChat/start openapi: 3.0.1 info: title: Starleads public API documentation description: > Welcome to the Starleads Public API documentation. This API provides public access to Starleads services, allowing developers and growth-hackers to interact with campaign-related data. *** ### Base endpoint ```https://api.starleads.co``` *** ### Errors The API uses standard HTTP status codes to indicate the success or failure of the API call. In case of failure, the body of the response will be JSON in the following format: ``` { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "No campaign exists with campaignId : 11111111" } ``` The ```type``` property is a link to a general description of the error type. *** ### Authentification Authentication for the API is handled with an API key that must be provided as a ```X-Api-Key``` header for every request.
**API keys are supposed to be a secret that only the client and server know. Please remember to not share them with anyone.**
You can find your API keys when authenticated in your Starleads profile :
![Api key menu option](../images/api-menu-option-screenshot.png) version: v1 x-logo: url: https://api.starleads.co/images/starleads-logo.png servers: [] security: [] tags: - name: Agent description: >- Manage your AI agent's prompt. These endpoints allow you to read and update the prompt that drives your agent's behavior during calls. - name: CampaignField description: >- CampaignFields enables users to specify customizable fields within their campaigns. These fields serve as placeholders (e.g., ```{lastname}```) that can be dynamically filled with corresponding data when creating prompts, providing flexibility in tailoring campaign content based on specific variables.
**Those are the keys of the ```databag``` field of the request payload to add a new ```CampaignItem``` to a campaign.** - name: CampaignItem description: Represents prospects entries related to a campaign - name: Consumption description: >- Track your company's credit consumption. These endpoints expose your current balance, usage and billing period so you can build budget monitoring on top of the API. - name: Subscription description: >- Inspect your subscription contract: the plan you are on, your subscription status, the features currently active and your effective limits. No pricing information is exposed. - name: AgentTest description: >- Tests of your agents: simulation tests (a simulated user talks to the agent and each success criterion is judged) and classification tests (the agent must produce the expected tag for a conversation). A test belongs to one agent. - name: AgentTestExecution description: >- Executions of agent tests: launching a set of tests, following their progress and cancelling them. One execution groups the runs created together for a list of tests, each repeated up to 5 times. - name: AgentTestFolder description: >- Folders grouping the tests of an agent (flat, with a name, a color and a markdown body). - name: AgentTestRun description: >- Runs of agent tests: one run is one attempt of one test inside an execution. Results, history and cancellation. - name: SimulationChat description: >- Test an agent through a text chat, exactly as it would behave in a real conversation (prompt, fields and connected tools included). Start a chat, then exchange messages with the agent. paths: /SimulationChat/start: post: tags: - SimulationChat summary: Start a simulation chat with an agent description: >- Starts a new text conversation with the agent and returns its identifier, the messages so far (the agent's welcome message, if any) and the agent definition. The agent must belong to the same company as the API key. Use `toolMocking` to keep the agent's tools from triggering real actions on your systems during the chat. operationId: StartSimulationChat parameters: - name: X-Api-Key in: header description: Api key to pass as a ```X-Api-Key``` request header. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/StartSimulationChatRequest' text/json: schema: $ref: '#/components/schemas/StartSimulationChatRequest' application/*+json: schema: $ref: '#/components/schemas/StartSimulationChatRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SimulationChatResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '422': description: Client Error content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '502': description: Server Error content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' components: schemas: StartSimulationChatRequest: required: - agentId type: object properties: agentId: minLength: 1 type: string description: ID of the agent to test dataBag: type: object additionalProperties: type: string description: >- Optional values for the agent's fields (the variables used in the prompt), e.g. { "firstName": "Marie" } nullable: true toolMocking: $ref: '#/components/schemas/PublicToolMocking' additionalProperties: false SimulationChatResponse: type: object properties: simulationChatId: type: string description: >- Identifier of the simulation chat (the conversation id). Pass it to SimulationChat/send-message. nullable: true messages: type: array items: $ref: '#/components/schemas/SimulationChatMessage' description: All the messages of the conversation so far, in chronological order nullable: true agent: $ref: '#/components/schemas/PublicAgent' additionalProperties: false description: >- State of a simulation chat, returned by SimulationChat/start and GET SimulationChat/{simulationChatId} ProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true additionalProperties: {} PublicToolMocking: type: object properties: mockedTools: type: array items: $ref: '#/components/schemas/PublicMockedTool' description: >- Tools to mock, targeted by their id (see the agent's connected tools). Each one returns its `resultTemplate` instead of being executed. nullable: true mockAllTools: type: boolean description: >- Mocks every tool connected to the agent. Tools listed in `mockedTools` keep their own template; the others return a default response telling the agent the call succeeded. Default false. mockCallTransfer: type: boolean description: >- Mocks the call transfer, so the simulation never transfers to a human. Independent of `mockAllTools`: a phone agent with call transfer enabled places a real transfer unless this is true. Default false. additionalProperties: false description: >- Which tools of the agent are mocked (not really executed) during a simulation. Every mock is opt-in: nothing is mocked unless asked for here, and `mockAllTools` does not imply `mockCallTransfer`. The knowledge base retrieval always runs for real. SimulationChatMessage: type: object properties: role: type: string description: '"assistant" for the agent, "user" for the simulated contact' nullable: true text: type: string description: Message text nullable: true timestamp: type: string description: Message timestamp format: date-time nullable: true isConversationEnded: type: boolean description: True when the agent decided to end the conversation endReason: type: string description: Why the conversation ended, when it did nullable: true additionalProperties: false description: A message exchanged in a simulation chat PublicAgent: type: object properties: agentId: type: string description: Agent identifier nullable: true agentName: type: string description: Agent name nullable: true prompt: type: string description: Prompt of the agent nullable: true tools: type: array items: $ref: '#/components/schemas/PublicTool' description: Tools connected to the agent nullable: true additionalProperties: false description: 'An agent: its name, prompt and connected tools' PublicMockedTool: required: - toolId type: object properties: toolId: minLength: 1 type: string description: ID of the tool to mock. It must be connected to the agent. resultTemplate: type: string description: >- Result handed back to the agent instead of the real one. Supports `{name}` placeholders resolved against the call parameters and the conversation variables. Empty: a default response telling the agent the call succeeded. nullable: true delaySeconds: maximum: 60 minimum: 0 type: number description: Simulated execution time, in seconds (0 to 60). Default 0. format: double additionalProperties: false PublicTool: type: object properties: id: type: string description: Tool identifier nullable: true name: type: string description: Human-readable tool name nullable: true technicalName: type: string description: Technical name (snake_case) used by the LLM to call the tool nullable: true additionalProperties: false description: A tool connected to an agent ````