Casafari API and MCP Platform Alerts API Webhooks API

openapi: 3.2.0
info:
  title: Casafari Alerts API Webhooks API
  description: 'The Casafari API provides clients with methods for manipulating alerts feeds, accounts, and consulting a reference

    of available locations, features and conditions.


    # Authentication methods


    -->'
  version: 0.1.0
servers:
- url: https://api.casafari.com
tags:
- name: alerts-api---webhooks
  x-displayName: Webhooks
paths:
  /alerts-api/webhooks:
    put:
      tags:
      - alerts-api---webhooks
      summary: Set webhook URL
      description: 'Sets (or replaces) the delivery URL for **all** your alert feeds.


        Before saving, a **GET** request is sent to the URL — your server must respond with HTTP **200**, otherwise this endpoint returns **400**.


        Alert deliveries themselves arrive as **POST** requests with a JSON array body.


        The URL is stored per user: changing it here instantly affects every feed, including alerts already queued for delivery. Feeds cannot be created until the webhook is configured.


        A signing secret is provisioned on the first call and returned in `secret` **once**; later calls return `secret: null`. Lost it? Use `POST /webhooks/rotate-secret`.'
      operationId: alerts-api__put__webhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertsApiSetWebhookRequestSchema'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertsApiSetWebhookResponseSchema'
        '400':
          description: Webhook URL verification failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertsApiErrorDetailSchema'
              example:
                detail: 'Webhook URL verification failed: Expected HTTP 200, got 404.'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertsApiHTTPValidationError'
      security:
      - HTTPBearer: []
      - OAuth2ClientCredentials: []
  /alerts-api/webhooks/rotate-secret:
    post:
      tags:
      - alerts-api---webhooks
      summary: Rotate signing secret
      description: 'Issues a new current signing secret. By default the previous secrets stay valid for a **24-hour grace window** so you can install the new key before removing the old one. Pass `{"immediate": true}` to revoke all previous secrets right away — use this only when a secret is compromised.'
      operationId: alerts-api__post__webhooks__rotate-secret
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertsApiRotateSecretRequestSchema'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertsApiRotateSecretResponseSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertsApiHTTPValidationError'
      security:
      - HTTPBearer: []
      - OAuth2ClientCredentials: []
components:
  schemas:
    AlertsApiHTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/AlertsApiValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AlertsApiRotateSecretResponseSchema:
      properties:
        secret:
          type: string
          title: Secret
      type: object
      required:
      - secret
      title: RotateSecretResponseSchema
    AlertsApiValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AlertsApiErrorDetailSchema:
      properties:
        detail:
          type: string
          title: Detail
      type: object
      required:
      - detail
      title: ErrorDetailSchema
    AlertsApiSetWebhookRequestSchema:
      properties:
        url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Url
      type: object
      required:
      - url
      title: SetWebhookRequestSchema
    AlertsApiRotateSecretRequestSchema:
      properties:
        immediate:
          type: boolean
          title: Immediate
          description: When false (default), the previous secrets keep working for a 24-hour grace window so you can switch the new secret before the old one stops signing; deliveries carry a signature for each active secret meanwhile. When true, the previous secrets are revoked immediately and only the new one signs — use this only when a secret is compromised.
          default: false
      type: object
      title: RotateSecretRequestSchema
    AlertsApiSetWebhookResponseSchema:
      properties:
        url:
          type: string
          title: Url
        secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Secret
      type: object
      required:
      - url
      - secret
      title: SetWebhookResponseSchema
  securitySchemes:
    HTTPBearer:
      type: http
      description: '

        Sign in with your account: `POST /login` with your email and password returns an `access_token` and a

        `refresh_token`. Send the access token as `Authorization: Bearer <access_token>`. When it expires, call

        `GET /refresh-token` with `Authorization: Bearer <refresh_token>` for a new access token.

        '
      scheme: bearer
      bearerFormat: JWT
    OAuth2ClientCredentials:
      type: oauth2
      description: "**Recommended.** Create a client in Settings → API Clients and save its ID and secret. The secret is displayed only once, and the client can be used only in the environment where it was created.\n\nExchange the client ID and secret for an access token using HTTP Basic authentication:\n\n```bash\ncurl -X POST 'https://api.casafari.com/oauth/token' \\\n  -u 'CLIENT_ID:CLIENT_SECRET' \\\n  -d 'grant_type=client_credentials' \\\n  -d 'scope=api'\n```\n\nThe access token is valid for 30 minutes. No refresh token is issued, so you must request a new access token when the current one expires.\n\nInclude the access token in API requests using the following header:\n\n```\nAuthorization: Bearer <token>\n```"
      flows:
        clientCredentials:
          scopes:
            api: Access to the CASAFARI REST API.
          tokenUrl: https://api.casafari.com/oauth/token
x-tagGroups:
- name: User Management
  tags:
  - user-management---authentication
- name: API
  tags:
  - api---valuation
  - api---alerts
  - api---comparables
  - api---references
  - api---properties
- name: Market Analytics API
  tags:
  - market-analytics-api---time series
  - market-analytics-api---distributions
  - market-analytics-api---analysis
- name: Alerts API
  tags:
  - alerts-api---webhooks
  - alerts-api---feeds