openapi: 3.1.0
info:
  title: Alvanate Developer API
  version: 2026-07-20
  description: Read-only, business-scoped operating resources. Test and live environments remain isolated.
servers:
  - url: https://alvanate.com
paths:
  /api/v1/businesses:
    get:
      operationId: listBusinesses
      summary: List businesses available to the credential
      security:
        - AlvanateKey: []
        - AlvanateOAuth: [businesses:read]
      responses:
        "200":
          description: Bounded business list
          headers:
            Alvanate-Version:
              schema: { type: string, const: 2026-07-20 }
            X-RateLimit-Limit:
              schema: { type: integer }
            X-RateLimit-Remaining:
              schema: { type: integer }
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListResponse"
  /api/v1/businesses/{businessId}/monitoring:
    get:
      operationId: getBusinessMonitoring
      summary: Read activity and provider-confirmed performance summaries
      security:
        - AlvanateKey: []
        - AlvanateOAuth: [monitoring:read]
      parameters:
        - $ref: "#/components/parameters/BusinessId"
      responses:
        "200": { $ref: "#/components/responses/Resource" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /api/v1/businesses/{businessId}/money:
    get:
      operationId: getBusinessMoney
      summary: Read provider-confirmed financial summaries
      security:
        - AlvanateKey: []
        - AlvanateOAuth: [money:read]
      parameters:
        - $ref: "#/components/parameters/BusinessId"
      responses:
        "200": { $ref: "#/components/responses/Resource" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /api/v1/businesses/{businessId}/orders:
    get:
      operationId: listBusinessOrders
      summary: List minimized order and fulfillment records
      security:
        - AlvanateKey: []
        - AlvanateOAuth: [orders:read]
      parameters:
        - $ref: "#/components/parameters/BusinessId"
      responses:
        "200": { $ref: "#/components/responses/Resource" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /api/v1/businesses/{businessId}/products:
    get:
      operationId: listBusinessProducts
      summary: List verified catalog facts and eligible product media
      security:
        - AlvanateKey: []
        - AlvanateOAuth: [products:read]
      parameters:
        - $ref: "#/components/parameters/BusinessId"
      responses:
        "200": { $ref: "#/components/responses/Resource" }
        "403": { $ref: "#/components/responses/Forbidden" }
components:
  securitySchemes:
    AlvanateKey:
      type: apiKey
      in: header
      name: X-Alvanate-Key
    AlvanateOAuth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://alvanate.com/oauth/authorize
          tokenUrl: https://alvanate.com/api/oauth/token
          refreshUrl: https://alvanate.com/api/oauth/token
          scopes:
            businesses:read: Read selected business identity and status
            monitoring:read: Read selected business activity and alerts
            money:read: Read selected business financial summaries
            orders:read: Read selected business orders
            products:read: Read selected business products
  parameters:
    BusinessId:
      name: businessId
      in: path
      required: true
      schema: { type: string, minLength: 1, maxLength: 180 }
  schemas:
    ListResponse:
      type: object
      required: [ok, data, meta]
      properties:
        ok: { type: boolean, const: true }
        data: { type: array, items: { type: object, additionalProperties: true } }
        meta: { type: object, additionalProperties: true }
    ResourceResponse:
      type: object
      required: [ok, data]
      properties:
        ok: { type: boolean, const: true }
        data: { type: object, additionalProperties: true }
    ErrorResponse:
      type: object
      required: [ok, error]
      properties:
        ok: { type: boolean, const: false }
        error: { type: string }
  responses:
    Resource:
      description: Scoped resource
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ResourceResponse" }
    Forbidden:
      description: Scope or business access denied
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ErrorResponse" }
