# חוזה OpenAPI

> תיעוד מקור. מקור: postman/openapi.yaml · 6a466bf.

המפרט המלא של חוזי ה־API הקיימים בקובץ המקור.

```yaml
openapi: 3.1.0
info:
  title: LinkNodes Energy API
  version: 0.1.0
  description: >
    Versioned API contract for LinkNodes Energy. Browser session APIs remain same-origin.
    Native iOS/Android clients use a separate bearer-token client API.
servers:
  - url: https://product.linknodesenergy.com
    description: Production product
paths:
  /api/health:
    get:
      operationId: getHealth
      summary: Product health
      responses:
        '200':
          description: Healthy product surface
          content:
            application/json:
              schema:
                type: object
                required: [name, version, status, surface, mode]
                properties:
                  name: { type: string, const: LinkNodes Energy }
                  version: { type: string }
                  status: { type: string, const: ok }
                  surface: { type: string }
                  mode: { type: string }
  /api/reference/geography:
    get:
      operationId: getGeography
      summary: Israeli locality reference data
      responses:
        '200': { description: Geography rows }
  /api/reference/map:
    get:
      operationId: getEnergyMap
      summary: Public charging and fuel map reference data
      responses:
        '200': { description: Map payload }
  /api/reference/overview:
    get:
      operationId: getReferenceOverview
      summary: Public reference overview
      responses:
        '200': { description: Overview payload }
  /api/reference/cities:
    get:
      operationId: searchCities
      summary: Search cities
      parameters:
        - in: query
          name: q
          schema: { type: string }
      responses:
        '200': { description: City results }
  /api/reference/locations:
    get:
      operationId: searchLocations
      summary: Search charging/fuel locations
      parameters:
        - in: query
          name: q
          schema: { type: string }
        - in: query
          name: city
          schema: { type: string }
      responses:
        '200': { description: Location results }
  /api/reference/models:
    get:
      operationId: searchVehicleModels
      summary: Search vehicle model catalog
      parameters:
        - in: query
          name: q
          schema: { type: string }
        - in: query
          name: id
          schema: { type: string }
      responses:
        '200': { description: Vehicle model results }
  /api/reference/vehicle:
    post:
      operationId: lookupRegisteredVehicle
      summary: Same-origin authenticated vehicle lookup
      description: Browser-only endpoint. Requires same-origin request, Clerk identity and quota.
      responses:
        '200': { description: Vehicle lookup result }
        '403': { description: Authorization denied }
        '429': { description: Daily quota exceeded }
  /api/platform/{path}:
    get:
      operationId: platformGet
      summary: Same-origin authenticated customer platform API
      description: Browser-session API; do not expose as a generic external API.
      parameters:
        - in: path
          name: path
          required: true
          schema: { type: string }
      responses:
        '200': { description: Platform payload }
        '401': { description: Not authenticated }
        '403': { description: Not authorized }

  /api/client/v1/context:
    get:
      operationId: getMobileClientContext
      summary: Authenticated mobile account context
      description: Native iOS/Android endpoint. Requires a Clerk session JWT in the Authorization Bearer header.
      security:
        - ClerkSession: []
      responses:
        '200':
          description: Active tenant memberships and tenant summaries for the signed-in user
        '401':
          description: Missing or invalid Clerk session token
  /api/client/v1/tenants/{tenantId}/context:
    get:
      operationId: getMobileTenantContext
      summary: Authenticated mobile tenant context
      description: Re-checks membership and tenant status under Supabase RLS for the requested tenant.
      security:
        - ClerkSession: []
      parameters:
        - in: path
          name: tenantId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Tenant and active membership
        '401':
          description: Missing or invalid Clerk session token
        '403':
          description: Tenant access denied
components:
  securitySchemes:
    ClerkSession:
      type: http
      scheme: bearer
      bearerFormat: JWT

  /api/client/v1/tenants/{tenantId}/overview:
    get:
      operationId: getMobileOverview
      summary: Mobile workspace overview
      security: [{ ClerkSession: [] }]
      parameters:
        - in: path
          name: tenantId
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200': { description: Workspace metrics and recent sessions }
        '403': { description: Tenant access denied }
  /api/client/v1/tenants/{tenantId}/vehicles:
    get:
      operationId: getMobileVehicles
      summary: Mobile fleet vehicles
      security: [{ ClerkSession: [] }]
      parameters:
        - in: path
          name: tenantId
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200': { description: Tenant-scoped vehicle list }
        '403': { description: Tenant access denied }
  /api/client/v1/tenants/{tenantId}/providers:
    get:
      operationId: getMobileProviders
      summary: Selected providers and provider directory rows
      security: [{ ClerkSession: [] }]
      parameters:
        - in: path
          name: tenantId
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200': { description: Tenant-scoped provider selection }
        '403': { description: Tenant access denied }
  /api/client/v1/tenants/{tenantId}/energy:
    get:
      operationId: getMobileEnergy
      summary: Unified EV and fuel ledger for the selected month
      security: [{ ClerkSession: [] }]
      parameters:
        - in: path
          name: tenantId
          required: true
          schema: { type: string, format: uuid }
        - in: query
          name: from
          schema: { type: string, format: date }
        - in: query
          name: to
          schema: { type: string, format: date }
      responses:
        '200': { description: Tenant-scoped unified energy ledger }
        '403': { description: Energy access denied }

  /api/client/v1/tenants/{tenantId}/map:
    get:
      operationId: getMobileEnergyMap
      summary: Tenant-scoped charging locations inside the visible map viewport
      description: Returns at most 400 charging locations for providers selected by the active tenant. Requires Clerk Bearer session auth and re-checks tenant membership under Supabase RLS.
      security: [{ ClerkSession: [] }]
      parameters:
        - in: path
          name: tenantId
          required: true
          schema: { type: string, format: uuid }
        - in: query
          name: north
          required: true
          schema: { type: number }
        - in: query
          name: south
          required: true
          schema: { type: number }
        - in: query
          name: east
          required: true
          schema: { type: number }
        - in: query
          name: west
          required: true
          schema: { type: number }
      responses:
        '200':
          description: Tenant-filtered charging locations and selected provider metadata
        '400':
          description: Invalid or oversized viewport
        '401':
          description: Missing or invalid Clerk session token
        '403':
          description: Tenant access denied
```
