FairePlace Usage API

openapi: 3.2.0
info:
  title: FairePlace Property Management Usage API
  description: 'Comprehensive API for managing properties, leases, tenants, and all aspects of real estate management.

    Built with Rust and Actix-web following hexagonal architecture principles.


    ## Authentication

    This API uses API keys for authentication with tenant-based isolation.


    ## Base URL

    - Production: `https://api.faireplace.com/api`'
  version: 1.0.0
  contact:
    name: FairePlace API Support
    email: api-support@faireplace.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.faireplace.com/api
  description: Production server
security:
- BearerAuth: []
tags:
- name: Usage
  description: Subscription plan usage and limits (consumption summary).
paths:
  /usage/summary:
    get:
      operationId: getUsageSummary
      summary: Get usage summary
      description: 'Returns the tenant''s current subscription plan and per-resource usage

        against plan limits.


        ## Resources


        Each entry reports `current` usage and, where applicable, the `limit`

        and `remaining` quota. A `null` `limit` (and `remaining`) means the

        resource is unlimited on the current plan.


        ## Cache


        Plan data is cached. Pass `force_refresh=true` to invalidate the cache

        and fetch fresh plan limits.


        ## Usage Example


        ```bash

        curl -X GET "https://api.faireplace.com/api/usage/summary" \

        -H "Authorization: Bearer YOUR_API_KEY"


        # Force a fresh fetch

        curl -X GET "https://api.faireplace.com/api/usage/summary?force_refresh=true" \

        -H "Authorization: Bearer YOUR_API_KEY"

        ```


        **Response**:

        ```json

        {

        "plan": "pro",

        "resources": [

        { "resource_type": "estate", "current": 5, "limit": 10, "remaining": 5 },

        { "resource_type": "signature", "current": 42, "limit": 100, "remaining": 58, "period": "monthly" }

        ]

        }

        ```'
      tags:
      - Usage
      security:
      - BearerAuth: []
      parameters:
      - name: force_refresh
        in: query
        required: false
        description: 'When `true`, invalidates the plan cache and fetches fresh plan limits.

          '
        schema:
          type: boolean
          default: false
        example: false
      responses:
        '200':
          description: The usage summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageSummaryResponse'
              examples:
                summary:
                  summary: Plan with mixed limits
                  value:
                    plan: pro
                    resources:
                    - resource_type: estate
                      current: 5
                      limit: 10
                      remaining: 5
                    - resource_type: signature
                      current: 42
                      limit: 100
                      remaining: 58
                      period: monthly
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    UsageSummaryResponse:
      type: object
      description: 'Summary of the tenant''s plan and current resource usage.

        '
      required:
      - plan
      - resources
      properties:
        plan:
          type: string
          description: 'Identifier of the tenant''s current subscription plan.

            '
          example: pro
        resources:
          type: array
          description: Per-resource usage entries.
          items:
            $ref: '#/components/schemas/ResourceUsage'
    Error:
      type: object
      description: "The error envelope returned by every authenticated endpoint.\n\nTwo things are worth knowing before you write your error handling:\n\n- **`code` is a symbolic string, not a number.** The numeric HTTP status is\n  in `status`. Branch on `code`: it is stable, and show `message`, which\n  is written for humans and may be reworded without notice.\n- The public guest-signature endpoints use a **different, flatter shape**\n  (`{ \"error_code\": …, \"message\": … }`, no `error` wrapper), because they\n  are consumed by a page that has no session. Their responses document it\n  inline.\n\nThe `X-Request-Id` response header carries the request identifier: quote it\nwhen reporting a problem. It is a header, not a body field.\n"
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - status
          properties:
            code:
              type: string
              description: Stable symbolic code. Branch on this.
              enum:
              - NOT_FOUND
              - UNAUTHORIZED
              - VALIDATION_ERROR
              - DATABASE_ERROR
              - BUSINESS_ERROR
              - STORAGE_ERROR
              - CONFIG_ERROR
              - FORBIDDEN
              - CONFLICT
              - PARSE_ERROR
              - SERIALIZATION_ERROR
              - AUTHENTICATION_ERROR
              - AUTHORIZATION_ERROR
              - EXTERNAL_SERVICE_ERROR
              - RATE_LIMIT_EXCEEDED
              - PAYMENT_REQUIRED
              - PLAN_LIMIT_REACHED
              - GONE
              - BAD_REQUEST
              - INTERNAL_ERROR
              - INTERNAL_SERVER_ERROR
              example: NOT_FOUND
            message:
              type: string
              description: 'Human-readable explanation, most often in French. Safe to display,

                not safe to parse.

                '
              example: Lease not found
            status:
              type: integer
              description: The HTTP status code, repeated in the body.
              example: 404
            details:
              type: object
              additionalProperties: true
              description: 'Extra machine-readable context. Only present on some errors: on

                `RATE_LIMIT_EXCEEDED` it carries `retry_after_seconds`.

                '
              example:
                retry_after_seconds: 12
    ResourceUsage:
      type: object
      description: 'Usage of a single resource against the tenant''s plan limit.

        '
      required:
      - resource_type
      - current
      properties:
        resource_type:
          type: string
          description: 'Identifier of the metered resource.


            Common values include `estate`, `lease_active`, `signature`,

            `media_storage_mb`, `team_member` and `export`.

            '
          enum:
          - estate
          - lease_active
          - signature
          - media_storage_mb
          - team_member
          - export
          example: signature
        current:
          type: integer
          format: int64
          description: Current usage count for this resource.
          example: 42
        limit:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Maximum allowed for the current plan. `null` means unlimited.

            '
          example: 100
        remaining:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Remaining quota (`limit - current`). `null` when the limit is unlimited.

            '
          example: 58
        period:
          type:
          - string
          - 'null'
          description: 'Reset period for the resource (e.g. `monthly`). Omitted when the

            resource is not periodic.

            '
          example: monthly
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key with fp_* prefix, passed as Bearer token
    WorkerApiKey:
      type: apiKey
      in: header
      name: X-API-Key
    WorkerBearer:
      type: http
      scheme: bearer
      bearerFormat: Worker