openapi: 3.2.0
info:
  title: CoworkingView Health API
  version: 1.0.0
  description: 'Read API for the CoworkingView catalogue plus the lead write path. Within a major version this contract is APPEND-ONLY: fields are added, never removed or retyped, because clients include mobile builds that cannot be recalled. A breaking change means /v2, with /v1 kept alive for at least two app releases.'
servers:
- url: https://api.coworkingview.com
  description: Production
- url: http://localhost:4000
  description: Local development
tags:
- name: Health
paths:
  /v1/health:
    get:
      operationId: health
      summary: Liveness probe; reports the deployed build sha
      description: Unauthenticated liveness check for the CoworkingView catalogue API. Returns the deployed git sha so a caller can confirm which build is serving traffic. No API key. Use this to verify the public API is reachable before issuing catalogue queries.
      tags:
      - Health
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        const: ok
                      sha:
                        type: string
                    required:
                    - status
                    - sha
                    additionalProperties: false
                  meta:
                    type: object
                    properties:
                      contractVersion:
                        type: string
                      pagination:
                        type: object
                        properties:
                          page:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          pageSize:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          total:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          pageCount:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                        required:
                        - page
                        - pageSize
                        - total
                        - pageCount
                        additionalProperties: false
                      truncated:
                        type: boolean
                      seed:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                    required:
                    - contractVersion
                    additionalProperties: false
                required:
                - data
                - meta
                additionalProperties: false
        '400':
          description: VALIDATION_FAILED
          content:
            application/problem+json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                    minimum: 400
                    maximum: 599
                  detail:
                    type: string
                  code:
                    type: string
                    enum:
                    - VALIDATION_FAILED
                    - NOT_FOUND
                    - RATE_LIMITED
                    - CHALLENGE_FAILED
                    - UPSTREAM_UNAVAILABLE
                    - INTERNAL_ERROR
                    - CLIENT_TOO_OLD
                    - IDEMPOTENCY_KEY_CONFLICT
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        message:
                          type: string
                      required:
                      - path
                      - message
                      additionalProperties: false
                  traceId:
                    type: string
                required:
                - type
                - title
                - status
                - code
                additionalProperties: false
        '429':
          description: RATE_LIMITED
          content:
            application/problem+json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                    minimum: 400
                    maximum: 599
                  detail:
                    type: string
                  code:
                    type: string
                    enum:
                    - VALIDATION_FAILED
                    - NOT_FOUND
                    - RATE_LIMITED
                    - CHALLENGE_FAILED
                    - UPSTREAM_UNAVAILABLE
                    - INTERNAL_ERROR
                    - CLIENT_TOO_OLD
                    - IDEMPOTENCY_KEY_CONFLICT
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        message:
                          type: string
                      required:
                      - path
                      - message
                      additionalProperties: false
                  traceId:
                    type: string
                required:
                - type
                - title
                - status
                - code
                additionalProperties: false
        '500':
          description: INTERNAL_ERROR
          content:
            application/problem+json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                    minimum: 400
                    maximum: 599
                  detail:
                    type: string
                  code:
                    type: string
                    enum:
                    - VALIDATION_FAILED
                    - NOT_FOUND
                    - RATE_LIMITED
                    - CHALLENGE_FAILED
                    - UPSTREAM_UNAVAILABLE
                    - INTERNAL_ERROR
                    - CLIENT_TOO_OLD
                    - IDEMPOTENCY_KEY_CONFLICT
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        message:
                          type: string
                      required:
                      - path
                      - message
                      additionalProperties: false
                  traceId:
                    type: string
                required:
                - type
                - title
                - status
                - code
                additionalProperties: false
        '502':
          description: UPSTREAM_UNAVAILABLE
          content:
            application/problem+json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                    minimum: 400
                    maximum: 599
                  detail:
                    type: string
                  code:
                    type: string
                    enum:
                    - VALIDATION_FAILED
                    - NOT_FOUND
                    - RATE_LIMITED
                    - CHALLENGE_FAILED
                    - UPSTREAM_UNAVAILABLE
                    - INTERNAL_ERROR
                    - CLIENT_TOO_OLD
                    - IDEMPOTENCY_KEY_CONFLICT
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        message:
                          type: string
                      required:
                      - path
                      - message
                      additionalProperties: false
                  traceId:
                    type: string
                required:
                - type
                - title
                - status
                - code
                additionalProperties: false