{
  "openapi": "3.1.1",
  "info": {
    "title": "CommuniQueue API",
    "description": "Send templated email, SMS, and webhook notifications from your application. Authenticate with a workspace API key in the X-Api-Key header.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.communiqueue.com"
    }
  ],
  "paths": {
    "/api/v1/notifications/send": {
      "post": {
        "tags": [
          "Notifications"
        ],
        "summary": "Send a templated notification",
        "description": "Queues a notification rendered from the template's live version. Omit versionNumber to always send whatever version is currently live; set it only to pin a specific published version.",
        "operationId": "Notifications_Send",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/NotificationRequest"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      }
    },
    "/api/v1/notifications/preview": {
      "post": {
        "tags": [
          "Notifications"
        ],
        "summary": "Preview a templated notification",
        "description": "Renders the template with the supplied tags without sending anything. Omit versionNumber to preview the live version; set it to preview a specific published version.",
        "operationId": "Notifications_Preview",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/NotificationRequest"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      }
    },
    "/api/v1/api-keys/validate": {
      "get": {
        "tags": [
          "ApiKeys"
        ],
        "operationId": "ApiKeys_Validate",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyValidationResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ApiKeyValidationResponse": {
        "required": [
          "isValid",
          "tenantId",
          "apiKeyId",
          "name",
          "status",
          "createdAt",
          "lastUsedAt",
          "expiresAt",
          "revokedAt"
        ],
        "type": "object",
        "properties": {
          "isValid": {
            "type": "boolean"
          },
          "tenantId": {
            "type": [
              "null",
              "string"
            ],
            "format": "uuid"
          },
          "apiKeyId": {
            "type": [
              "null",
              "string"
            ],
            "format": "uuid"
          },
          "name": {
            "type": [
              "null",
              "string"
            ]
          },
          "status": {
            "type": [
              "null",
              "string"
            ]
          },
          "createdAt": {
            "type": [
              "null",
              "string"
            ],
            "format": "date-time"
          },
          "lastUsedAt": {
            "type": [
              "null",
              "string"
            ],
            "format": "date-time"
          },
          "expiresAt": {
            "type": [
              "null",
              "string"
            ],
            "format": "date-time"
          },
          "revokedAt": {
            "type": [
              "null",
              "string"
            ],
            "format": "date-time"
          }
        }
      },
      "AttachmentDto": {
        "required": [
          "name",
          "content",
          "contentType"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "content": {
            "type": "string"
          },
          "contentType": {
            "type": "string"
          },
          "cid": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "AttachmentMetadataDto": {
        "required": [
          "name",
          "contentType",
          "sizeBytes",
          "contentId"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "contentType": {
            "type": "string"
          },
          "sizeBytes": {
            "type": "integer",
            "format": "int64"
          },
          "contentId": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "BatchingInfoDto": {
        "required": [
          "emailType",
          "messageCount",
          "batchingStrategy"
        ],
        "type": "object",
        "properties": {
          "emailType": {
            "type": "string"
          },
          "messageCount": {
            "type": "integer",
            "format": "int32"
          },
          "batchingStrategy": {
            "type": "string"
          }
        }
      },
      "EmailOptionsDto": {
        "type": "object",
        "properties": {
          "fromAddress": {
            "type": [
              "null",
              "string"
            ]
          },
          "replyTo": {
            "type": [
              "null",
              "string"
            ]
          },
          "to": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "type": "string"
            }
          },
          "cc": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "type": "string"
            }
          },
          "bcc": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "type": "string"
            }
          },
          "overrideRecipients": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "type": "string"
            }
          },
          "attachments": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "$ref": "#/components/schemas/AttachmentDto"
            }
          },
          "priority": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EmailPriority"
              }
            ]
          },
          "sensitivity": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EmailSensitivity"
              }
            ]
          },
          "requestReadReceipt": {
            "type": "boolean",
            "default": false
          },
          "requestDeliveryReceipt": {
            "type": "boolean",
            "default": false
          },
          "trackOpens": {
            "type": [
              "null",
              "boolean"
            ]
          },
          "trackClicks": {
            "type": [
              "null",
              "boolean"
            ]
          },
          "customHeaders": {
            "type": [
              "null",
              "object"
            ],
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "EmailPreviewResultDto": {
        "required": [
          "success",
          "templateMetadata",
          "sender",
          "recipients",
          "renderedContent",
          "finalBodies",
          "variableMetadata",
          "batchingInfo",
          "attachments",
          "trackingSettings",
          "customHeaders",
          "renderingErrors",
          "errorMessage"
        ],
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "templateMetadata": {
            "$ref": "#/components/schemas/TemplateMetadataDto"
          },
          "sender": {
            "$ref": "#/components/schemas/EmailSenderDto"
          },
          "recipients": {
            "$ref": "#/components/schemas/ResolvedRecipientsDto"
          },
          "renderedContent": {
            "$ref": "#/components/schemas/RenderedContentDto"
          },
          "finalBodies": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/FinalBodiesDto"
              }
            ]
          },
          "variableMetadata": {
            "$ref": "#/components/schemas/VariableMetadataDto"
          },
          "batchingInfo": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/BatchingInfoDto"
              }
            ]
          },
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AttachmentMetadataDto"
            }
          },
          "trackingSettings": {
            "$ref": "#/components/schemas/TrackingSettingsDto"
          },
          "customHeaders": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "renderingErrors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RenderingErrorDto"
            }
          },
          "errorMessage": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "EmailPriority": {
        "enum": [
          "Normal",
          "High",
          "Low",
          null
        ]
      },
      "EmailSenderDto": {
        "required": [
          "fromAddress",
          "fromName",
          "replyTo"
        ],
        "type": "object",
        "properties": {
          "fromAddress": {
            "type": "string"
          },
          "fromName": {
            "type": [
              "null",
              "string"
            ]
          },
          "replyTo": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "EmailSensitivity": {
        "enum": [
          "Normal",
          "Personal",
          "Private",
          "Confidential",
          null
        ]
      },
      "FinalBodiesDto": {
        "required": [
          "htmlBody",
          "textBody"
        ],
        "type": "object",
        "properties": {
          "htmlBody": {
            "type": "string"
          },
          "textBody": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "NotificationRequest": {
        "required": [
          "tenantId",
          "templateId",
          "tags"
        ],
        "type": "object",
        "properties": {
          "tenantId": {
            "type": "string",
            "format": "uuid"
          },
          "templateId": {
            "type": "string",
            "format": "uuid"
          },
          "tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TagDto"
            }
          },
          "versionNumber": {
            "type": [
              "null",
              "integer"
            ],
            "format": "int32"
          },
          "emailOptions": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EmailOptionsDto"
              }
            ]
          },
          "smsOptions": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SmsOptionsDto"
              }
            ]
          },
          "webhookOptions": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/WebhookOptionsDto"
              }
            ]
          }
        }
      },
      "PreviewResponse": {
        "required": [
          "email",
          "validationErrors"
        ],
        "type": "object",
        "properties": {
          "email": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EmailPreviewResultDto"
              }
            ]
          },
          "validationErrors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ValidationErrorDto"
            }
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": [
              "null",
              "string"
            ]
          },
          "title": {
            "type": [
              "null",
              "string"
            ]
          },
          "status": {
            "type": [
              "null",
              "integer"
            ],
            "format": "int32"
          },
          "detail": {
            "type": [
              "null",
              "string"
            ]
          },
          "instance": {
            "type": [
              "null",
              "string"
            ]
          },
          "errorCode": {
            "type": [
              "null",
              "string"
            ],
            "description": "Stable machine-readable cause, for example api_keys.invalid. Branch on this rather than on the message."
          },
          "correlationId": {
            "type": [
              "null",
              "string"
            ],
            "description": "Identifier for this request. Quote it when contacting support."
          },
          "traceId": {
            "type": [
              "null",
              "string"
            ],
            "description": "Distributed trace identifier for this request."
          }
        }
      },
      "RenderedContentDto": {
        "required": [
          "subject",
          "body",
          "htmlHead"
        ],
        "type": "object",
        "properties": {
          "subject": {
            "type": [
              "null",
              "string"
            ]
          },
          "body": {
            "type": [
              "null",
              "string"
            ]
          },
          "htmlHead": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "RenderingErrorDto": {
        "required": [
          "templatePart",
          "message"
        ],
        "type": "object",
        "properties": {
          "templatePart": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ResolvedRecipientsDto": {
        "required": [
          "to",
          "cc",
          "bcc",
          "wasOverridden"
        ],
        "type": "object",
        "properties": {
          "to": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cc": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "bcc": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "wasOverridden": {
            "type": "boolean"
          }
        }
      },
      "SendResponse": {
        "required": [
          "accepted",
          "correlationId",
          "message"
        ],
        "type": "object",
        "properties": {
          "accepted": {
            "type": "boolean"
          },
          "correlationId": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "SmsOptionsDto": {
        "type": "object",
        "properties": {
          "fromNumber": {
            "type": [
              "null",
              "string"
            ]
          },
          "to": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "type": "string"
            }
          },
          "overrideRecipients": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "type": "string"
            }
          }
        }
      },
      "TagDto": {
        "required": [
          "key",
          "value"
        ],
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        }
      },
      "TemplateMetadataDto": {
        "required": [
          "templateId",
          "versionNumber",
          "emailType",
          "notificationType"
        ],
        "type": "object",
        "properties": {
          "templateId": {
            "type": "string",
            "format": "uuid"
          },
          "versionNumber": {
            "type": "integer",
            "format": "int32"
          },
          "emailType": {
            "type": "string"
          },
          "notificationType": {
            "type": "string"
          }
        }
      },
      "TrackingSettingsDto": {
        "required": [
          "trackOpens",
          "trackClicks"
        ],
        "type": "object",
        "properties": {
          "trackOpens": {
            "type": "boolean"
          },
          "trackClicks": {
            "type": "boolean"
          }
        }
      },
      "ValidationErrorDto": {
        "required": [
          "field",
          "message"
        ],
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "VariableMetadataDto": {
        "required": [
          "providedVariables",
          "missingVariables",
          "unusedVariables"
        ],
        "type": "object",
        "properties": {
          "providedVariables": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "missingVariables": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "unusedVariables": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "WebhookOptionsDto": {
        "type": "object",
        "properties": {
          "urlOverride": {
            "type": [
              "null",
              "string"
            ]
          },
          "headers": {
            "type": [
              "null",
              "object"
            ],
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "description": "Workspace API key. Create one in workspace settings. A key is scoped to a single workspace.",
        "name": "X-Api-Key",
        "in": "header"
      }
    }
  },
  "tags": [
    {
      "name": "Notifications"
    },
    {
      "name": "ApiKeys"
    }
  ]
}