openapi: "3.0.0"
info:
  title: "Make.com API"
  version: "1.0.0"
  description: "API endpoints for contact updates and event management."
servers:
  - url: "https://{gateway_key}.execute-api.us-east-1.amazonaws.com"
    variables:
      gateway_key:
        description: "Your Gateway Key from their API settings page."
        default: "your-gateway-key"
paths:
  "/users/updates":
    get:
      summary: "Retrieve contact updates"
      description: "Fetches contact updates over the given interval."
      security:
        - ApiKeyAuth: []
      parameters:
        - name: limit
          in: query
          description: "Number of records to return (pagination). Defaults to 100 if not specified."
          schema:
            type: integer
            default: 100
            example: 50
        - name: offset
          in: query
          description: "Number of records to skip before starting to return results."
          schema:
            type: integer
            example: 10
        - name: interval
          in: query
          description: "Time interval for filtering results (must be parseable by Golang, e.g., 20s or 24h)."
          schema:
            type: string
            example: "24h"
      responses:
        '200':
          description: "A list of contact updates, along with pagination and error information."
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: "#/components/schemas/User"
                  next_offset:
                    type: integer
                    example: 1
                  errors:
                    $ref: "#/components/schemas/Errors"
              example:
                users:
                  - id: "d991a5d9-1961-7f76-88ba-6f7fe40e9c94"
                    email: "myemail@swiftmissive.com"
                    first_name: "test"
                    last_name: "test"
                    date_of_birth: "2001-01-01T00:00:00Z"
                    timezone: "America/New_York"
                    json:
                      example_unstructured_data:
                        nested_value: 5
                    created_at: "2025-05-16T17:32:21Z"
                    unsubscribed_at: null

                    email_validated_at: "2025-05-16T17:28:36Z"
                    email_validation_result_string: "valid"
                next_offset: 1
                errors: []
                paths:
        '429':
          description: "The service is being called too many times.  The request can be retried."
        '500':
          description: "The service failed to respond to the request.  If CORS is mentioned, you are likely on the documentation page and forgot to provide your gateway and api keys?"
  "/users":
    post:
      summary: "Create or update contacts"
      description: >
        Creates new contacts or updates existing contacts in the system.
        Provide an array of contacts objects via the "users" property in the request body.
        The response will contain a "data" array with the resulting contact records and any errors.
      security:
        - ApiKeyAuth: []
      requestBody:
        description: "An object with a 'users' property containing an array of contact-information objects."
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                users:
                  type: array
                  items:
                    $ref: "#/components/schemas/User"
              required:
                - users
            example:
              users:
                - email: "myemail@swiftmissive.com"
                  first_name: "test"
                  last_name: "test"
                  date_of_birth: "2001-01-01T00:00:00Z"
                  timezone: "America/New_York"
                  json:
                    example_unstructured_data:
                      nested_value: 5
      responses:
        '200':
          description: "Contact created successfully."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserCreatedResponse"
              example:
                data:
                  - id: "d991a5d9-1961-7f76-88ba-6f7fe40e9c94"
                    email: "myemail@swiftmissive.com"
                    first_name: "test"
                    last_name: "test"
                    date_of_birth: "2001-01-01T00:00:00Z"
                    timezone: "America/New_York"
                    json:
                      example_unstructured_data:
                        nested_value: 5
                    created_at: "2025-05-16T17:32:21Z"
                    unsubscribed_at: null
                    email_validated_at: "2025-05-16T17:28:36Z"
                    email_validation_result_string: "valid"
                errors: []
                paths:
        '429':
          description: "The service is being called too many times.  The request can be retried."
        '500':
          description: "The service failed to respond to the request.  If CORS is mentioned, you are likely on the documentation page and forgot to provide your gateway and api keys?"
  "/events/updates":
    get:
      summary: "Retrieve event updates"
      description: "Fetches the latest updates related to events."
      security:
        - ApiKeyAuth: []
      parameters:
        - name: limit
          in: query
          description: "Number of records to return (pagination). Defaults to 100 if not specified."
          schema:
            type: integer
            default: 100
            example: 50
        - name: offset
          in: query
          description: "Number of records to skip before starting to return results."
          schema:
            type: integer
            example: 10
        - name: interval
          in: query
          description: "Time interval for filtering results (must be parseable by Golang, e.g., 20s or 24h)."
          schema:
            type: string
            example: "20s"
        - name: event_name
          in: query
          description: Sort order
          required: true
          schema:
            type: string
            enum:
            - email_send_result_success
            - ses_event_open
            - ses_event_click
            - ses_event_delivery
            - ses_event_bounce
            - user_unsubscribed
            - send_email_request
            - email_send_result_error
      responses:
        '200':
          description: "A list of event updates, including pagination data and errors."
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      $ref: "#/components/schemas/EventRecord"
                  next_offset:
                    type: integer
                    example: 1
                  errors:
                    $ref: "#/components/schemas/Errors"
              example:
                events:
                  - id: "cab0d473-c7b7-10f9-dc6f-520bcc3ca00f"
                    name: "user purchased product 1 tier 3"
                    user_id: "d991a5d9-1961-7f76-88ba-6f7fe40e9c94"
                    email: "myemail@swiftmissive.com"
                    user: null
                    json:
                      additional_info:
                        unstructured_data: "goes here"
                    metric1: 0
                    metric2: 0
                    metric3: 0
                    emitted_at: "2025-05-16T17:34:20.897961271Z"
                    created_at: "2025-05-16T17:34:20.897961187Z"
                next_offset: 1
                errors: []
                paths:
        '429':
          description: "The service is being called too many times.  The request can be retried."
        '500':
          description: "The service failed to respond to the request.  If CORS is mentioned, you are likely on the documentation page and forgot to provide your gateway and api keys?"
  "/events":
    post:
      summary: "Create events"
      description: >
        Creates new events in the system.
        Provide an object with an "events" property containing an array of event objects.
      security:
        - ApiKeyAuth: []
      requestBody:
        description: "An object with an 'events' property containing an array of event objects."
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                events:
                  type: array
                  items:
                    $ref: "#/components/schemas/Event"
              required:
                - events
            example:
              events:
                - name: "user purchased product 1 tier 3"
                  email: "myemail@swiftmissive.com"
                  json:
                    additional_info:
                      unstructured_data: "goes here"
      responses:
        '200':
          description: "Events created successfully."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventCreatedResponse"
              example:
                data:
                  - id: "cab0d473-c7b7-10f9-dc6f-520bcc3ca00f"
                    name: "user purchased product 1 tier 3"
                    user_id: "d991a5d9-1961-7f76-88ba-6f7fe40e9c94"
                    email: "myemail@swiftmissive.com"
                    user: null
                    json:
                      additional_info:
                        unstructured_data: "goes here"
                    metric1: 0
                    metric2: 0
                    metric3: 0
                    emitted_at: "2025-05-16T17:34:20.897961271Z"
                    created_at: "2025-05-16T17:34:20.897961187Z"
                errors: []
        '429':
          description: "The service is being called too many times.  The request can be retried."
        '500':
          description: "The service failed to respond to the request.  If CORS is mentioned, you are likely on the documentation page and forgot to provide your gateway and api keys?"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: "d991a5d9-1961-7f76-88ba-6f7fe40e9c94"
        email:
          type: string
          format: email
          example: "myemail@swiftmissive.com"
        first_name:
          type: string
          example: "test"
        last_name:
          type: string
          example: "test"
        date_of_birth:
          type: string
          format: date-time
          example: "2001-01-01T00:00:00Z"
        timezone:
          type: string
          example: "America/New_York"
        json:
          type: object
          additionalProperties: true
          example:
            example_unstructured_data:
              nested_value: 5
        created_at:
          type: string
          format: date-time
          example: "2025-05-16T17:32:21Z"
        unsubscribed_at:
          type: string
          format: date-time
          nullable: true
          example: null
        email_validated_at:
          type: string
          format: date-time
          example: "2025-05-16T17:28:36Z"
        email_validation_result_string:
          type: string
          example: "valid"
    UserCreatedResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/User"
        errors:
          $ref: "#/components/schemas/Errors"
    Event:
      type: object
      properties:
        name:
          type: string
          example: "user purchased product 1 tier 3"
        email:
          type: string
          format: email
          example: "myemail@swiftmissive.com"
        json:
          type: object
          additionalProperties: true
          example:
            additional_info:
              unstructured_data: "goes here"
      required:
        - name
        - email
    EventRecord:
      type: object
      properties:
        id:
          type: string
          example: "cab0d473-c7b7-10f9-dc6f-520bcc3ca00f"
        name:
          type: string
          description: "The type of event occurring."
          enum:
            - email_send_result_error
            - email_send_result_success
            - send_email_request
            - ses_event_bounce
            - ses_event_click
            - ses_event_delivery
            - ses_event_open
            - ses_event_send
            - user_unsubscribed
        user_id:
          type: string
          example: "d991a5d9-1961-7f76-88ba-6f7fe40e9c94"
        email:
          type: string
          format: email
          example: "myemail@swiftmissive.com"
        user:
          type: object
          nullable: true
          example: null
        json:
          type: object
          additionalProperties: true
          example:
            additional_info:
              unstructured_data: "goes here"
        metric1:
          type: integer
          example: 0
        metric2:
          type: integer
          example: 0
        metric3:
          type: integer
          example: 0
        emitted_at:
          type: string
          format: date-time
          example: "2025-05-16T17:34:20.897961271Z"
        created_at:
          type: string
          format: date-time
          example: "2025-05-16T17:34:20.897961187Z"
    EventCreatedResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/EventRecord"
        errors:
          $ref: "#/components/schemas/Errors"
    Errors:
      description: "An array of error messages, if any."
      type: array
      items:
        type: string
        example: "An error message"
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: "API key required for authentication. Set this to the API key from your API settings."
    GatewayKeyAuth:
      type: gatewayKey
      name: Gateway key
      description: "Gateway key required for authentication. Set this to the Gateway key from your API settings."
# Optionally, you can add a global security requirement:
security:
  - ApiKeyAuth: []
    GatewayKeyAuth: []
