{
  "openapi": "3.0.3",
  "info": {
    "title": "DataTranscribe API",
    "description": "Public API for DataTranscribe (datatranscribe.com) — AI-powered audio/video transcription. Authenticate with either a JWT bearer token (obtained via /api/auth/login or /api/auth/register + email confirmation) or a long-lived API key (obtained via /api/auth/api-key). Guest, unauthenticated access is available for short (<=120s) transcriptions via /api/upload/guest.",
    "version": "1.0.0",
    "contact": {
      "name": "DataTranscribe Support",
      "email": "info@datatranscribe.com",
      "url": "https://datatranscribe.com"
    }
  },
  "servers": [
    {
      "url": "https://datatranscribe.com",
      "description": "Production"
    }
  ],
  "security": [
    { "bearerAuth": [] },
    { "apiKeyAuth": [] }
  ],
  "tags": [
    { "name": "auth", "description": "Registration, login, session, and API key management" },
    { "name": "jobs", "description": "Transcription job status, retrieval, and deletion" },
    { "name": "upload", "description": "Uploading media for transcription" },
    { "name": "billing", "description": "Prepaid minute packages and Stripe checkout" },
    { "name": "integrations", "description": "Third-party integration connection status" }
  ],
  "paths": {
    "/api/auth/register": {
      "post": {
        "tags": ["auth"],
        "summary": "Register a new account",
        "description": "Creates an inactive account and emails a confirmation link. The account has 0 minutes until confirmed; confirming credits 5 free minutes.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/RegisterRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Registration accepted, confirmation email sent",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "pending_confirmation" },
                    "email": { "type": "string", "format": "email" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "description": "Email already registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/auth/confirm-email": {
      "get": {
        "tags": ["auth"],
        "summary": "Confirm email via link (browser redirect flow)",
        "description": "Followed from the confirmation email link. Activates the account, credits 5 free minutes, and redirects into the portal already logged in with an access token in the URL fragment.",
        "security": [],
        "parameters": [
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "302": { "description": "Redirects to the portal (success) or the homepage with an error flag (invalid token)" }
        }
      },
      "post": {
        "tags": ["auth"],
        "summary": "Confirm email (SPA/programmatic flow)",
        "description": "Same activation logic as the GET link, but returns JSON with a usable access token instead of redirecting.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["token"],
                "properties": { "token": { "type": "string" } }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account confirmed",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenResponse" } } }
          },
          "400": { "description": "Invalid or expired confirmation link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/auth/resend-confirm": {
      "post": {
        "tags": ["auth"],
        "summary": "Resend confirmation email",
        "description": "Always returns 200 to avoid email enumeration.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailOnlyRequest" } } }
        },
        "responses": {
          "200": { "description": "Generic acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessage" } } } }
        }
      }
    },
    "/api/auth/resend-confirmation": {
      "post": {
        "tags": ["auth"],
        "summary": "Resend confirmation email (alias)",
        "description": "Alias of /api/auth/resend-confirm.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailOnlyRequest" } } }
        },
        "responses": {
          "200": { "description": "Generic acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessage" } } } }
        }
      }
    },
    "/api/auth/login": {
      "post": {
        "tags": ["auth"],
        "summary": "Log in with email and password",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "password"],
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "password": { "type": "string", "format": "password" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Login successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenResponse" } } } },
          "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Email not confirmed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/auth/forgot-password": {
      "post": {
        "tags": ["auth"],
        "summary": "Request a password reset email",
        "description": "Always returns 200 to avoid email enumeration.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailOnlyRequest" } } }
        },
        "responses": {
          "200": { "description": "Generic acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessage" } } } }
        }
      }
    },
    "/api/auth/reset-password": {
      "post": {
        "tags": ["auth"],
        "summary": "Reset password using a reset token",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["token", "new_password"],
                "properties": {
                  "token": { "type": "string" },
                  "new_password": { "type": "string", "format": "password", "minLength": 8 }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Password updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessage" } } } },
          "400": { "description": "Invalid/expired token or password too short", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/auth/change-email": {
      "post": {
        "tags": ["auth"],
        "summary": "Change the authenticated user's email",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["new_email", "password"],
                "properties": {
                  "new_email": { "type": "string", "format": "email" },
                  "password": { "type": "string", "format": "password" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Email changed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "email": { "type": "string" } } } } } },
          "400": { "description": "Email already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Incorrect password", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/auth/change-password": {
      "post": {
        "tags": ["auth"],
        "summary": "Change the authenticated user's password",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["current_password", "new_password"],
                "properties": {
                  "current_password": { "type": "string", "format": "password" },
                  "new_password": { "type": "string", "format": "password", "minLength": 8 }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Password updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessage" } } } },
          "401": { "description": "Incorrect current password", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/auth/delete-account": {
      "post": {
        "tags": ["auth"],
        "summary": "Permanently delete the authenticated account",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["password"],
                "properties": { "password": { "type": "string", "format": "password" } }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Account deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessage" } } } },
          "401": { "description": "Incorrect password", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/auth/me": {
      "get": {
        "tags": ["auth"],
        "summary": "Get the current authenticated user",
        "responses": {
          "200": {
            "description": "Current user",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user_id": { "type": "string", "format": "uuid" },
                    "email": { "type": "string", "format": "email" },
                    "created_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/auth/api-key": {
      "get": {
        "tags": ["auth"],
        "summary": "Get (or lazily generate) the user's API key",
        "responses": {
          "200": { "description": "API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }
        }
      }
    },
    "/api/auth/api-key/rotate": {
      "post": {
        "tags": ["auth"],
        "summary": "Rotate the user's API key",
        "description": "Generates a brand new key, immediately invalidating the old one.",
        "responses": {
          "200": { "description": "New API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }
        }
      }
    },
    "/api/jobs": {
      "get": {
        "tags": ["jobs"],
        "summary": "List the authenticated user's transcription jobs",
        "parameters": [
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 200 } }
        ],
        "responses": {
          "200": {
            "description": "Job history, newest first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/JobListItem" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/jobs/{job_id}/status": {
      "get": {
        "tags": ["jobs"],
        "summary": "Get a job's status",
        "parameters": [
          { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } },
          "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/jobs/{job_id}/transcript": {
      "get": {
        "tags": ["jobs"],
        "summary": "Get a job's transcript text",
        "description": "May return partial text while the job is still processing.",
        "parameters": [
          { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Transcript", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptResponse" } } } },
          "404": { "description": "Job not found, or transcript not available yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/jobs/{job_id}/srt": {
      "get": {
        "tags": ["jobs"],
        "summary": "Download a job's SRT subtitle file",
        "parameters": [
          { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "SRT file", "content": { "text/plain": { "schema": { "type": "string", "format": "binary" } } } },
          "404": { "description": "Job or SRT not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/jobs/{job_id}/vtt": {
      "get": {
        "tags": ["jobs"],
        "summary": "Download a job's WebVTT subtitle file",
        "parameters": [
          { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "VTT file", "content": { "text/vtt": { "schema": { "type": "string", "format": "binary" } } } },
          "404": { "description": "Job or VTT not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/jobs/{job_id}": {
      "delete": {
        "tags": ["jobs"],
        "summary": "Delete a job and its files",
        "description": "Only deletes jobs owned by the authenticated user.",
        "parameters": [
          { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessage" } } } },
          "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/upload": {
      "post": {
        "tags": ["upload"],
        "summary": "Upload media for transcription (authenticated)",
        "description": "Deducts from the user's minute balance. If balance is insufficient, transcribes as much as the balance covers (partial transcription) rather than blocking. Supports resuming from a previous partial job for the same filename.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "file": { "type": "string", "format": "binary" },
                  "target_language": { "type": "string", "default": "original", "description": "Target translation language, or 'original' to keep source language" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } } },
          "400": { "description": "Unsupported file type, file too large, or unreadable media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "402": { "description": "Insufficient balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "500": { "description": "Upload failed; balance not charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/upload/guest": {
      "post": {
        "tags": ["upload"],
        "summary": "Upload media for transcription (unauthenticated guest)",
        "description": "No account required. Transcribes up to 120 seconds; longer media is trimmed to the first 120 seconds and marked partial.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "file": { "type": "string", "format": "binary" },
                  "target_language": { "type": "string", "default": "original" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } } },
          "400": { "description": "Unsupported file type, file too large, or unreadable media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/packages": {
      "get": {
        "tags": ["billing"],
        "summary": "List available prepaid minute packages",
        "security": [],
        "responses": {
          "200": {
            "description": "Package catalogue",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } }
              }
            }
          }
        }
      }
    },
    "/api/buy-package": {
      "post": {
        "tags": ["billing"],
        "summary": "Create a Stripe Checkout session for a minute package",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["package"],
                "properties": {
                  "package": { "type": "string", "enum": ["starter", "pro", "extended"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout session created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string" },
                    "url": { "type": "string", "format": "uri" }
                  }
                }
              }
            }
          },
          "400": { "description": "Unknown package or misconfigured price ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/verify-session": {
      "get": {
        "tags": ["billing"],
        "summary": "Poll a Stripe Checkout session for credit status",
        "parameters": [
          { "name": "session_id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Pending or credited status",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "type": "object", "properties": { "status": { "type": "string", "enum": ["pending"] } } },
                    {
                      "type": "object",
                      "properties": {
                        "status": { "type": "string", "enum": ["credited"] },
                        "package": { "type": "string" },
                        "minutes_credited": { "type": "number" },
                        "minutes_remaining": { "type": "number" }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/integrations/status": {
      "get": {
        "tags": ["integrations"],
        "summary": "Get connection status for all third-party integrations",
        "description": "Covers Google Drive, Notion, Zapier, and Slack. The connect/callback endpoints for these are browser OAuth redirect flows (not JSON APIs) and are omitted from this schema; use this status endpoint plus each provider's /disconnect endpoint programmatically.",
        "responses": {
          "200": {
            "description": "Per-provider connection status",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationsStatus" } } }
          }
        }
      }
    },
    "/api/integrations/google-drive/disconnect": {
      "post": {
        "tags": ["integrations"],
        "summary": "Disconnect Google Drive",
        "responses": {
          "200": { "description": "Disconnected (or already not connected)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessage" } } } }
        }
      }
    },
    "/api/integrations/notion/disconnect": {
      "post": {
        "tags": ["integrations"],
        "summary": "Disconnect Notion",
        "responses": {
          "200": { "description": "Disconnected (or already not connected)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessage" } } } }
        }
      }
    },
    "/api/integrations/zapier/connect": {
      "post": {
        "tags": ["integrations"],
        "summary": "Generate a Zapier API key",
        "description": "Zapier uses per-user API key auth rather than OAuth, so this is a direct JSON endpoint rather than a redirect flow.",
        "responses": {
          "200": {
            "description": "Zapier key issued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "status": { "type": "string" }, "zapier_key": { "type": "string" } }
                }
              }
            }
          }
        }
      }
    },
    "/api/integrations/zapier/disconnect": {
      "post": {
        "tags": ["integrations"],
        "summary": "Disconnect Zapier",
        "responses": {
          "200": { "description": "Disconnected (or already not connected)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessage" } } } }
        }
      }
    },
    "/api/integrations/slack/disconnect": {
      "post": {
        "tags": ["integrations"],
        "summary": "Disconnect Slack",
        "responses": {
          "200": { "description": "Disconnected (or already not connected)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessage" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Obtained from /api/auth/login, /api/auth/register + /api/auth/confirm-email, or the Google sign-in flow. Expires per JWT_EXPIRATION_HOURS (default 24h)."
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Long-lived key from GET /api/auth/api-key, for programmatic/non-browser access."
      }
    },
    "schemas": {
      "RegisterRequest": {
        "type": "object",
        "required": ["email", "password"],
        "properties": {
          "email": { "type": "string", "format": "email" },
          "password": { "type": "string", "format": "password" }
        }
      },
      "EmailOnlyRequest": {
        "type": "object",
        "required": ["email"],
        "properties": { "email": { "type": "string", "format": "email" } }
      },
      "AuthTokenResponse": {
        "type": "object",
        "properties": {
          "access_token": { "type": "string" },
          "token_type": { "type": "string", "example": "bearer" },
          "user_id": { "type": "string", "format": "uuid" },
          "email": { "type": "string", "format": "email" },
          "minutes_remaining": { "type": "number" },
          "already_confirmed": { "type": "boolean" }
        }
      },
      "ApiKeyResponse": {
        "type": "object",
        "properties": {
          "api_key": { "type": "string", "example": "dt_1a2b3c..." }
        }
      },
      "StatusMessage": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "message": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "detail": {
            "oneOf": [
              { "type": "string" },
              { "type": "object" }
            ]
          }
        }
      },
      "JobListItem": {
        "type": "object",
        "properties": {
          "job_id": { "type": "string" },
          "status": { "type": "string", "enum": ["uploaded", "processing", "completed", "failed"] },
          "original_filename": { "type": "string" },
          "duration_seconds": { "type": "number" },
          "created_at": { "type": "string", "format": "date-time" },
          "completed_at": { "type": "string", "format": "date-time", "nullable": true },
          "error_message": { "type": "string", "nullable": true }
        }
      },
      "JobStatusResponse": {
        "type": "object",
        "properties": {
          "job_id": { "type": "string" },
          "status": { "type": "string" },
          "original_filename": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "completed_at": { "type": "string", "format": "date-time", "nullable": true },
          "error_message": { "type": "string", "nullable": true }
        }
      },
      "TranscriptResponse": {
        "type": "object",
        "properties": {
          "job_id": { "type": "string" },
          "text": { "type": "string" },
          "duration_seconds": { "type": "number" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "UploadResponse": {
        "type": "object",
        "properties": {
          "job_id": { "type": "string" },
          "status": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "is_partial": { "type": "boolean" },
          "trimmed_minutes": { "type": "number" },
          "full_minutes": { "type": "number" },
          "target_language": { "type": "string" }
        }
      },
      "Package": {
        "type": "object",
        "properties": {
          "key": { "type": "string", "enum": ["starter", "pro", "extended"] },
          "name": { "type": "string" },
          "minutes": { "type": "integer" },
          "price_dollars": { "type": "number" },
          "description": { "type": "string" }
        }
      },
      "IntegrationsStatus": {
        "type": "object",
        "properties": {
          "google_drive": {
            "type": "object",
            "properties": {
              "connected": { "type": "boolean" },
              "email": { "type": "string", "nullable": true },
              "connected_at": { "type": "string", "format": "date-time", "nullable": true }
            }
          },
          "notion": {
            "type": "object",
            "properties": {
              "connected": { "type": "boolean" },
              "workspace_name": { "type": "string", "nullable": true },
              "connected_at": { "type": "string", "format": "date-time", "nullable": true }
            }
          },
          "zapier": {
            "type": "object",
            "properties": {
              "connected": { "type": "boolean" },
              "connected_at": { "type": "string", "format": "date-time", "nullable": true }
            }
          },
          "slack": {
            "type": "object",
            "properties": {
              "connected": { "type": "boolean" },
              "team_name": { "type": "string", "nullable": true },
              "channel_name": { "type": "string", "nullable": true },
              "connected_at": { "type": "string", "format": "date-time", "nullable": true }
            }
          }
        }
      }
    }
  }
}