openapi: 3.0.3
info:
  title: Esperaly Public API
  version: v1
  description: Queue (location) and ticket (entry) REST. Authenticate with API keys.
servers:
  - url: "{CONVEX_SITE_URL}/api/v1"
    variables:
      CONVEX_SITE_URL:
        default: https://your-deployment.convex.site
paths:
  /locations:
    get:
      summary: List locations
      security: [{ bearerAuth: [] }]
      responses:
        "200": { description: Location list }
        "401": { description: Invalid API key }
  /queues:
    get:
      summary: List queues (locations)
      security: [{ bearerAuth: [] }]
      responses:
        "200": { description: Queue list }
  /queues/{queueId}:
    get:
      summary: Get one queue
      security: [{ bearerAuth: [] }]
      parameters:
        - in: path
          name: queueId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Queue }
        "404": { description: Not found }
  /queues/{queueId}/entries:
    get:
      summary: List active entries
      security: [{ bearerAuth: [] }]
      parameters:
        - in: path
          name: queueId
          required: true
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer, maximum: 100 }
        - in: query
          name: cursor
          schema: { type: string }
      responses:
        "200": { description: Page of entries }
    post:
      summary: Create an entry
      security: [{ bearerAuth: [] }]
      parameters:
        - in: header
          name: Idempotency-Key
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [serviceId]
              properties:
                serviceId: { type: string }
                customerName: { type: string }
                customerEmail: { type: string }
                customerPhone: { type: string }
                fieldValues:
                  type: object
                  additionalProperties: { type: string }
      responses:
        "201": { description: Created }
  /entries/{entryId}:
    get:
      summary: Get an entry
      security: [{ bearerAuth: [] }]
      parameters:
        - in: path
          name: entryId
          required: true
          schema: { type: string }
      responses:
        "200": { description: Entry }
    patch:
      summary: Not supported in v1
      responses:
        "405": { description: Method not allowed }
  /entries/{entryId}/call:
    post:
      summary: Move entry to Call Next status
      security: [{ bearerAuth: [] }]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                counterId: { type: string }
      responses:
        "200": { description: Updated entry }
  /entries/{entryId}/cancel:
    post:
      summary: Cancel using the workflow leave status
      security: [{ bearerAuth: [] }]
      responses:
        "200": { description: Updated entry }
  /entries/{entryId}/complete:
    post:
      summary: Complete using the workflow complete status
      security: [{ bearerAuth: [] }]
      responses:
        "200": { description: Updated entry }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: esperaly_live_