SLNG Sessions API

openapi: 3.0.3
info:
  title: SLNG Voice Agents Account Sessions API
  version: 1.0.0
  description: 'Public API for managing Voice Agents, dispatching outbound calls, and creating web (non-telephony) sessions.


    Base URL: `https://api.agents.slng.ai`

    '
  contact:
    name: SLNG Support
    email: support@slng.ai
servers:
- url: https://api.agents.slng.ai
  description: Production
security:
- bearerAuth: []
tags:
- name: Sessions
  description: Web (non-telephony) sessions.
paths:
  /v1/agents/{agent_id}/web-sessions:
    parameters:
    - $ref: '#/components/parameters/AgentIdPath'
    post:
      operationId: createWebSession
      summary: Create web session
      description: 'Create a browser session for a voice agent.


        This is commonly used for in-browser testing without PSTN.

        '
      tags:
      - Sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentWebSessionCreate'
      responses:
        '200':
          description: Web session created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentWebSessionResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          description: Payment required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                insufficient-credits:
                  summary: Organisation balance is depleted
                  value:
                    detail: Insufficient credit balance. Please top up credits or upgrade your plan.
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          description: Bad gateway.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                web-session-dispatch-failed:
                  summary: Upstream dispatch failure
                  value:
                    detail: 'Failed to dispatch web session: upstream dispatcher unavailable'
components:
  responses:
    BadRequestError:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            bad-request:
              summary: Generic bad request
              value:
                detail: The request could not be processed.
    ForbiddenError:
      description: Forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            forbidden:
              summary: Access denied
              value:
                detail: You do not have access to this resource.
    NotFoundError:
      description: Not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            not-found:
              summary: Resource not found
              value:
                detail: The requested resource was not found.
    ValidationError:
      description: Validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            validation-error:
              summary: Request validation failed
              value:
                detail:
                - loc:
                  - body
                  - language
                  msg: Input should be a valid string
                  type: string_type
    UnauthorizedError:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized:
              summary: Authentication failed
              value:
                detail: Authentication is required for this endpoint.
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal-server-error:
              summary: Unexpected application error
              value:
                detail: An unexpected internal error occurred.
  schemas:
    UUID:
      type: string
      format: uuid
      example: 550e8400-e29b-41d4-a716-446655440000
    AgentWebSessionCreate:
      type: object
      additionalProperties: false
      properties:
        arguments:
          type: object
          maxProperties: 32
          additionalProperties:
            type: string
            maxLength: 1024
          default: {}
          description: Per-session template argument overrides. Maximum 32 keys. Each value may be up to 1024 characters. Combined value payload may not exceed 8192 characters.
        participant_name:
          type: string
          nullable: true
          description: Optional display name for the web participant.
    ErrorResponse:
      type: object
      additionalProperties: true
      description: 'Error payloads can vary depending on where the error is raised (edge gateway vs backend).


        Common shapes include:

        - `{ "error": "message" }`

        - `{ "detail": "message" }`

        - `{ "detail": [ { "loc": [...], "msg": "...", "type": "..." } ] }` (validation)

        '
      properties:
        error:
          type: string
        detail:
          oneOf:
          - type: string
          - type: array
            items:
              type: object
    AgentWebSessionResponse:
      type: object
      additionalProperties: false
      required:
      - call_id
      - room_name
      - livekit_url
      - livekit_token
      - max_session_seconds
      - message
      properties:
        call_id:
          $ref: '#/components/schemas/UUID'
        room_name:
          type: string
          description: Internal session identifier for advanced browser integrations.
        livekit_url:
          type: string
          description: Browser session transport URL.
        livekit_token:
          type: string
          description: Browser session access token.
        max_session_seconds:
          type: integer
          minimum: 60
        message:
          type: string
          example: Web session created successfully
  parameters:
    AgentIdPath:
      name: agent_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
      description: Voice agent ID.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key