{
  "openapi": "3.1.0",
  "info": {
    "title": "Otipi API",
    "version": "1",
    "summary": "Email, SMS and login codes for apps in Israel, through one API.",
    "description": "Send email, SMS and login codes (by SMS, WhatsApp or email) to recipients in Israel.\n\nCall the API from a server only: the key is a secret, and the API sends no CORS headers.\n\nA key that starts with sk_test_ works in test mode: nothing is delivered, messages appear in the log, and /v1/otp/send returns the code in test_code.\n\nSMS and WhatsApp go to Israeli mobile numbers only, written as +9725XXXXXXXX. Limits: 600 requests a minute per key, 5 codes an hour per recipient.\n\nIntegrations: for Supabase Auth (Auth -> Hooks -> Send SMS Hook), use https://otipi.co.il/v1/integrations/supabase-sms-hook?channel=auto. For Lovable and Cursor, see /llms-full.txt. For Base44, import /openapi.json.\n\nDocumentation: https://otipi.co.il/en/docs. The same text for AI tools: https://otipi.co.il/llms-full.txt."
  },
  "servers": [
    {
      "url": "https://otipi.co.il"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Login codes",
      "description": "Send a code, then check what the person typed."
    },
    {
      "name": "Messages",
      "description": "Send one message and follow what happens to it."
    }
  ],
  "paths": {
    "/v1/otp/send": {
      "post": {
        "tags": [
          "Login codes"
        ],
        "operationId": "sendLoginCode",
        "summary": "Send a login code",
        "description": "Makes a code, sends it and keeps it for checking. In test mode the code comes back in test_code and nothing is delivered.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OtpSend"
              },
              "example": {
                "to": "+972501234567",
                "app": "MyApp"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The code is on its way.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Otp"
                },
                "example": {
                  "id": "otp_Hc91VdKq2mZx8LpT4rNb",
                  "status": "pending",
                  "to": "+972501234567",
                  "channel": "sms",
                  "message_id": "msg_7Qk2LxWb9RtY3nPd5sAe",
                  "expires_at": "2026-11-10T08:20:02.000Z",
                  "test_code": "482917"
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, wrong or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient prepaid balance in wallet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Real sending is not open for this account or channel yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The request is not valid: see error.code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests, or too many codes for this recipient.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The carrier could not take the code right now.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/otp/verify": {
      "post": {
        "tags": [
          "Login codes"
        ],
        "operationId": "verifyLoginCode",
        "summary": "Check a login code",
        "description": "Checks the latest code sent to this recipient. A code can be tried 5 times. Sign the person in only when valid is true.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OtpVerify"
              },
              "example": {
                "to": "+972501234567",
                "code": "482917"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Whether the code is right.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OtpResult"
                },
                "example": {
                  "valid": true
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, wrong or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "to or code is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "tags": [
          "Messages"
        ],
        "operationId": "sendMessage",
        "summary": "Send a message",
        "description": "Accepts one email or SMS and sends it. The answer comes at once, before the message has left; follow it with GET /v1/messages/{id} or with webhooks.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 255
            },
            "description": "A value of your own. A second request with the same value returns the first message and sends nothing."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessageInput"
              },
              "example": {
                "channel": "sms",
                "to": "+972501234567",
                "template": "login-code",
                "variables": {
                  "code": "482917",
                  "app": "MyApp",
                  "minutes": 5
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The same Idempotency-Key was used before: this is the earlier message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                }
              }
            }
          },
          "202": {
            "description": "Accepted and queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, wrong or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient prepaid balance in wallet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Real sending is not possible yet: see error.code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The request is not valid: see error.code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "A limit was reached: see error.code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Messages"
        ],
        "operationId": "listMessages",
        "summary": "List the latest messages",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "channel",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "email",
                "sms",
                "whatsapp"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "queued",
                "sent",
                "delivered",
                "opened",
                "failed",
                "bounced"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The newest messages first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "has_more"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Message"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, wrong or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages/{id}": {
      "get": {
        "tags": [
          "Messages"
        ],
        "operationId": "getMessage",
        "summary": "One message and everything that happened to it",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The message with its events.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Message"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "events": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "type": {
                                "type": "string"
                              },
                              "detail": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, wrong or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "There is no such message in this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/integrations/supabase-sms-hook": {
      "post": {
        "tags": [
          "Login codes"
        ],
        "operationId": "supabaseSmsHook",
        "summary": "Supabase Auth Send SMS Hook",
        "description": "Accepts a standard Supabase Auth Send SMS Hook payload ({ user: { phone }, sms: { otp } }) and sends the OTP via Otipi (sms, whatsapp or auto via ?channel=auto).",
        "parameters": [
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "sms",
                "whatsapp",
                "auto"
              ],
              "default": "sms"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SupabaseSmsHook"
              },
              "example": {
                "user": {
                  "phone": "+972501234567"
                },
                "sms": {
                  "otp": "482917"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The code was accepted for sending.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false
                },
                "example": {}
              }
            }
          },
          "401": {
            "description": "The key or signature is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient prepaid balance in wallet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The request is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "A limit was reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "messageEvent": {
      "post": {
        "summary": "A message changed its status",
        "description": "Sent to each address added in the dashboard. Answer with a 2xx code within 8 seconds; otherwise it is tried again after 10 seconds and after a minute. The header Otipi-Signature is \"t=<unix seconds>,v1=<hex HMAC-SHA256 of t + \".\" + raw body, keyed with the secret of the address>\".",
        "parameters": [
          {
            "name": "Otipi-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Received."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from the dashboard: sk_test_... or sk_live_..."
      }
    },
    "schemas": {
      "OtpSend": {
        "type": "object",
        "required": [
          "to",
          "app"
        ],
        "properties": {
          "to": {
            "type": "string",
            "description": "An Israeli mobile number such as +972501234567, or an email address when channel is email."
          },
          "app": {
            "type": "string",
            "maxLength": 40,
            "description": "The name your users know you by. It appears in the message."
          },
          "channel": {
            "type": "string",
            "enum": [
              "sms",
              "whatsapp",
              "email",
              "auto"
            ],
            "default": "sms",
            "description": "When auto is used, Otipi tries WhatsApp first and falls back to SMS if the provider fails."
          },
          "language": {
            "type": "string",
            "enum": [
              "he",
              "ar",
              "ru",
              "en"
            ],
            "default": "he",
            "description": "The language of the message."
          },
          "length": {
            "type": "integer",
            "minimum": 4,
            "maximum": 8,
            "default": 6,
            "description": "Digits in the code. A real WhatsApp code always has 6."
          },
          "ttl_minutes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 30,
            "default": 5,
            "description": "How long the code is valid. A real WhatsApp code is always valid for 5 minutes."
          },
          "from": {
            "type": "string",
            "description": "For SMS: an approved sender name. For email: an address on a verified domain."
          }
        }
      },
      "Otp": {
        "type": "object",
        "required": [
          "id",
          "status",
          "to",
          "channel",
          "message_id",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending"
            ]
          },
          "to": {
            "type": "string"
          },
          "channel": {
            "type": "string",
            "enum": [
              "sms",
              "whatsapp",
              "email"
            ]
          },
          "message_id": {
            "type": "string",
            "description": "The message that carries the code. Follow its delivery with GET /v1/messages/{id}."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "test_code": {
            "type": "string",
            "description": "The code itself. Present in test mode only."
          }
        }
      },
      "OtpVerify": {
        "type": "object",
        "required": [
          "to",
          "code"
        ],
        "properties": {
          "to": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "What the person typed."
          }
        }
      },
      "SupabaseSmsHook": {
        "type": "object",
        "required": [
          "user",
          "sms"
        ],
        "properties": {
          "user": {
            "type": "object",
            "required": [
              "phone"
            ],
            "properties": {
              "phone": {
                "type": "string"
              }
            }
          },
          "sms": {
            "type": "object",
            "required": [
              "otp"
            ],
            "properties": {
              "otp": {
                "type": "string"
              }
            }
          }
        }
      },
      "OtpResult": {
        "type": "object",
        "required": [
          "valid"
        ],
        "properties": {
          "valid": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "enum": [
              "wrong_code",
              "expired_or_missing",
              "too_many_attempts"
            ],
            "description": "Present when valid is false."
          }
        }
      },
      "MessageInput": {
        "type": "object",
        "required": [
          "channel",
          "to"
        ],
        "properties": {
          "channel": {
            "type": "string",
            "enum": [
              "email",
              "sms",
              "whatsapp"
            ],
            "description": "With a live key WhatsApp carries login codes only: use /v1/otp/send for them."
          },
          "to": {
            "type": "string",
            "description": "An email address, or an Israeli mobile number such as +972501234567."
          },
          "from": {
            "type": "string",
            "description": "Email: \"My App <hello@myapp.co.il>\" on a verified domain; required with a live key. SMS: an approved sender name of 3 to 11 Latin letters or digits; the first approved name is used when left out."
          },
          "subject": {
            "type": "string",
            "maxLength": 300,
            "description": "Required for email, unless a template gives one."
          },
          "text": {
            "type": "string",
            "description": "The content. An SMS can be up to 10 parts and 1,005 characters."
          },
          "html": {
            "type": "string",
            "description": "An HTML version for email. Built from text when left out."
          },
          "template": {
            "type": "string",
            "description": "The name of a template, in place of text: login-code, order-confirmed, receipt, or one of your own."
          },
          "variables": {
            "type": "object",
            "additionalProperties": true,
            "description": "The values that go into the template."
          },
          "language": {
            "type": "string",
            "enum": [
              "he",
              "ar",
              "ru",
              "en"
            ],
            "default": "he",
            "description": "For the ready-made templates."
          }
        }
      },
      "Message": {
        "type": "object",
        "required": [
          "id",
          "channel",
          "to",
          "status",
          "mode",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "channel": {
            "type": "string",
            "enum": [
              "email",
              "sms",
              "whatsapp"
            ]
          },
          "to": {
            "type": "string"
          },
          "from": {
            "type": [
              "string",
              "null"
            ]
          },
          "subject": {
            "type": [
              "string",
              "null"
            ]
          },
          "template": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "sent",
              "delivered",
              "opened",
              "failed",
              "bounced"
            ],
            "description": "queued: accepted. sent: handed to the carrier. delivered: reached the recipient. opened: the email was opened. failed: could not be sent, see error. bounced: the email came back."
          },
          "mode": {
            "type": "string",
            "enum": [
              "test",
              "live"
            ]
          },
          "segments": {
            "type": [
              "integer",
              "null"
            ],
            "description": "SMS parts. Null for other channels."
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "sent_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "delivered_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "opened_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "Event": {
        "type": "object",
        "required": [
          "id",
          "type",
          "created_at",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "message.sent",
              "message.delivered",
              "message.opened",
              "message.failed",
              "message.bounced"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "$ref": "#/components/schemas/Message"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "account_suspended",
                  "rate_limited",
                  "invalid_json",
                  "invalid_request",
                  "payload_too_large",
                  "method_not_allowed",
                  "internal_error",
                  "invalid_channel",
                  "invalid_recipient",
                  "invalid_sender",
                  "missing_subject",
                  "missing_content",
                  "missing_sender",
                  "missing_app",
                  "unknown_template",
                  "missing_variables",
                  "message_too_long",
                  "domain_not_verified",
                  "sender_required",
                  "sender_not_approved",
                  "identity_not_verified",
                  "live_unavailable",
                  "whatsapp_codes_only",
                  "links_not_allowed",
                  "insufficient_balance",
                  "recipient_rate_limit",
                  "test_limit_reached",
                  "monthly_limit_reached",
                  "daily_limit_reached",
                  "too_many_codes",
                  "provider_error",
                  "not_found"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}