{
  "openapi": "3.0.3",
  "info": {
    "title": "FetchInbox Testing & Mailbox API",
    "description": "FetchInbox provides email OTP and magic-link testing infrastructure for Playwright, CI, and automated software workflows.",
    "version": "1.13.0"
  },
  "servers": [
    {
      "url": "https://fetchinbox.com",
      "description": "Primary Production Gateway"
    },
    {
      "url": "https://getotp.ccwu.cc",
      "description": "Legacy Compatibility Gateway"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Commercial project API key starting with fi_live_... (legacy getotp_live_... keys remain fully supported)"
      },
      "AddressJwtAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Address JWT returned when creating or logging into an ephemeral mailbox"
      }
    }
  },
  "paths": {
    "/api/new_address": {
      "post": {
        "summary": "Create an Ephemeral Mailbox",
        "description": "Workflow A (Ephemeral Mailbox). Generates an isolated disposable inbox returning an address, password, and Address JWT.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Optional mailbox name prefix"
                  },
                  "domain": {
                    "type": "string",
                    "description": "Target domain from available domain cluster"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mailbox successfully created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "address": {
                      "type": "string"
                    },
                    "jwt": {
                      "type": "string"
                    },
                    "password": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "address",
                    "jwt"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Creation disabled or invalid parameters"
          }
        }
      }
    },
    "/api/parsed_mails": {
      "get": {
        "summary": "Poll Pre-Parsed Structured Emails (Workflow A)",
        "description": "Retrieves pre-parsed structured emails for the authenticated ephemeral address. Edge extraction parses text, html, sender, subject, and attachments without client-side MIME overhead.",
        "security": [
          {
            "AddressJwtAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of parsed emails",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "sender": {
                            "type": "string"
                          },
                          "subject": {
                            "type": "string"
                          },
                          "text": {
                            "type": "string"
                          },
                          "html": {
                            "type": "string"
                          },
                          "created_at": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid address token"
          }
        }
      }
    },
    "/api/mails": {
      "get": {
        "summary": "Fetch Raw MIME Messages (Workflow A Fallback)",
        "description": "Retrieves raw RFC822 messages. Use only when raw message debugging or unparsed MIME headers are specifically required.",
        "security": [
          {
            "AddressJwtAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of raw emails"
          },
          "400": {
            "description": "Missing or invalid address token"
          }
        }
      }
    },
    "/user_api/register": {
      "post": {
        "summary": "Provision Commercial Account & Live API Key (Workflow B)",
        "description": "Automated account provisioning for test suites and CI workflows. Provisions an account, default project, and returns a live API key (fi_live_...).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account created and live API key returned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "api_key": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "success",
                    "api_key"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "User already exists or invalid registration request"
          }
        }
      }
    },
    "/v1/runs": {
      "post": {
        "summary": "Create an Isolated Verification Run (Workflow B)",
        "description": "Creates an isolated verification session for parallel testing. Allocates a dedicated email inbox with lifecycle limits and concurrency enforcement.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lease_minutes": {
                    "type": "integer",
                    "default": 60,
                    "maximum": 1440
                  },
                  "address_ttl_hours": {
                    "type": "integer",
                    "default": 1,
                    "maximum": 24
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Run created with dedicated email",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run_id": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "lease_expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "address_expires_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "run_id",
                    "email"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: invalid or missing API key"
          },
          "429": {
            "description": "Concurrency limit reached for current entitlement"
          }
        }
      }
    },
    "/v1/runs/{id}": {
      "get": {
        "summary": "Get Verification Run Status",
        "description": "Inspects status, email address, and lifecycle expiry timestamps for an active or finished run.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verification run details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "project_id": {
                      "type": "string"
                    },
                    "email_address": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "active",
                        "pass",
                        "fail",
                        "expired",
                        "cancelled"
                      ]
                    },
                    "created_at": {
                      "type": "string"
                    },
                    "lease_expires_at": {
                      "type": "string"
                    },
                    "address_expires_at": {
                      "type": "string"
                    },
                    "finished_at": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Verification run not found"
          }
        }
      }
    },
    "/v1/runs/{id}/match": {
      "get": {
        "summary": "Poll Structured Match Result (Workflow B)",
        "description": "Polls for verification results returned as structured data (OTP or magic-link). Edge regex and link extraction parse matching inbound emails without requiring full message body retrieval.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "otp",
                "magic_link"
              ],
              "default": "otp"
            }
          },
          {
            "name": "sender",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Match polling result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "matched",
                        "pending",
                        "extract_no_match",
                        "ambiguous_match",
                        "expired"
                      ]
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "otp",
                        "magic_link"
                      ]
                    },
                    "value": {
                      "type": "string",
                      "description": "Extracted OTP code when type=otp and status=matched"
                    },
                    "url": {
                      "type": "string",
                      "description": "Extracted verification link when type=magic_link and status=matched"
                    },
                    "message_id": {
                      "type": "string"
                    },
                    "received_at": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Verification run not found"
          }
        }
      }
    },
    "/v1/runs/{id}/finish": {
      "post": {
        "summary": "Finish Verification Run & Trigger Cleanup (Workflow B)",
        "description": "Completes the verification run with pass, fail, or cancel status. Releasing concurrency slots immediately; passing runs trigger immediate deletion of raw email bodies.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "result": {
                    "type": "string",
                    "enum": [
                      "pass",
                      "fail"
                    ]
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "pass",
                      "fail",
                      "cancel"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Run successfully finished and concurrency released",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "pass",
                        "fail",
                        "cancelled"
                      ]
                    },
                    "finished_at": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Verification run not found"
          },
          "409": {
            "description": "Run already finished"
          }
        }
      }
    },
    "/v1/account/usage": {
      "get": {
        "summary": "Get Entitlement & Account Usage Telemetry",
        "description": "Returns active commercial entitlement, monthly inbound quota, live storage volume, and concurrency slot allocation.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account usage summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account_id": {
                      "type": "string"
                    },
                    "plan": {
                      "type": "string",
                      "enum": [
                        "free",
                        "developer",
                        "team"
                      ]
                    },
                    "entitlement_status": {
                      "type": "string",
                      "enum": [
                        "active",
                        "canceled",
                        "expired",
                        "past_due"
                      ]
                    },
                    "period_start": {
                      "type": "string"
                    },
                    "paid_through": {
                      "type": "string"
                    },
                    "used_inbound_saved": {
                      "type": "integer"
                    },
                    "max_monthly_inbound": {
                      "type": "integer"
                    },
                    "live_raw_bytes": {
                      "type": "integer"
                    },
                    "max_live_raw_bytes": {
                      "type": "integer"
                    },
                    "concurrency": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/api/wait_for_otp": {
      "get": {
        "summary": "Wait for OTP or Magic Link in mailbox",
        "description": "Polls server-side for an incoming verification code or magic link within a bounded wait window, collapsing client polling loops.",
        "parameters": [
          {
            "name": "x-custom-auth",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Address password or custom authentication if configured"
          },
          {
            "name": "Authorization",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Bearer <jwt> returned when address was created"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "code",
                "link"
              ],
              "default": "all"
            },
            "description": "Type of verification token to extract"
          },
          {
            "name": "sender",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by sender address"
          },
          {
            "name": "subject",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by subject substring"
          },
          {
            "name": "after_checkpoint",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO-8601 checkpoint: only match mail arrived after this timestamp"
          },
          {
            "name": "wait_seconds",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 8,
              "default": 3
            },
            "description": "Max seconds to hold request waiting for mail"
          }
        ],
        "responses": {
          "200": {
            "description": "Extraction result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "match",
                        "extract_no_match",
                        "ambiguous_match",
                        "timeout",
                        "no_mail"
                      ]
                    },
                    "code": {
                      "type": "string",
                      "nullable": true
                    },
                    "link": {
                      "type": "string",
                      "nullable": true
                    },
                    "message_id": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/runs/{id}/messages": {
      "get": {
        "summary": "List verification run messages with representation support",
        "description": "Retrieves messages delivered to this verification run. Supports representation=parsed for sanitized structured fallback or raw MIME.",
        "security": [
          {
            "BearerApiKey": []
          },
          {
            "HeaderApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Verification Run ID"
          },
          {
            "name": "representation",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "raw",
                "parsed"
              ],
              "default": "raw"
            },
            "description": "Message representation level: parsed (Level 1) or raw (Level 2)"
          }
        ],
        "responses": {
          "200": {
            "description": "Run messages list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "run_id": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "representation": {
                      "type": "string",
                      "enum": [
                        "raw",
                        "parsed"
                      ]
                    },
                    "messages": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized API key"
          },
          "404": {
            "description": "Run not found"
          }
        }
      }
    },
    "/v1/runs/{id}/result": {
      "get": {
        "summary": "Get verification run match result (alias for /match)",
        "description": "Public alias for /v1/runs/{id}/match",
        "security": [
          {
            "BearerApiKey": []
          },
          {
            "HeaderApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Verification Run ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Match response identical to /v1/runs/{id}/match"
          }
        }
      }
    }
  }
}