{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "description": "API key returned by POST /v0/agent/sign-up (format bi_live_...).",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "contact": {
      "email": "support@botsinbox.com",
      "name": "BotsInbox",
      "url": "https://botsinbox.com"
    },
    "description": "Email inboxes for AI agents. Free unlimited email RECEIVING for AI agents and bots: an agent creates its own account with one API call (no human signup), creates inboxes programmatically, and reads incoming email via REST or the hosted MCP server. Verification codes (OTPs) are extracted automatically into the extracted_code field. Sending email is a paid-plan feature. Limits on the free plan: 5 inboxes per account, messages retained 30 days.",
    "license": {
      "name": "Terms",
      "url": "https://botsinbox.com/docs"
    },
    "title": "BotsInbox API",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/v0/agent/sign-up": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "agent_name": {
                    "type": "string"
                  },
                  "invite_code": {
                    "description": "Optional founder invite code. Raises the account to 10 inboxes and 90-day retention.",
                    "type": "string"
                  },
                  "owner_email": {
                    "format": "email",
                    "type": "string"
                  },
                  "purpose": {
                    "type": "string"
                  }
                },
                "required": [
                  "agent_name",
                  "owner_email"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Account created. The api_key is shown once - store it."
          }
        },
        "security": [],
        "summary": "Agent self-sign-up: create an account and get an API key in one call. No human involved."
      }
    },
    "/v0/inboxes": {
      "get": {
        "responses": {
          "200": {
            "description": "Array of inboxes."
          }
        },
        "summary": "List the account's inboxes (free plan: up to 5)."
      },
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "display_name": {
                    "type": "string"
                  },
                  "local_part": {
                    "description": "Address name before @botsinbox.com. Generated if omitted.",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Inbox created."
          },
          "403": {
            "description": "inbox_cap_reached - free plan allows 5 inboxes per account."
          }
        },
        "summary": "Create an inbox, e.g. research-bot@botsinbox.com."
      }
    },
    "/v0/inboxes/{inbox_id}/messages": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "inbox_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Messages with subject, sender, snippet and extracted_code when a verification code was found."
          }
        },
        "summary": "List messages in an inbox, newest first."
      }
    },
    "/v0/inboxes/{inbox_id}/messages:send": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "inbox_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "402": {
            "description": "plan_required - sending is a paid-plan feature."
          }
        },
        "summary": "Send email (PAID PLAN). Returns 402 plan_required on the free plan."
      }
    },
    "/v0/me": {
      "get": {
        "responses": {
          "200": {
            "description": "Account."
          }
        },
        "summary": "The authenticated account."
      }
    },
    "/v0/messages/{message_id}": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "message_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full message."
          }
        },
        "summary": "Get one message in full: text body, reply-extracted body_text_clean, attachments list, extracted_code, prompt_injection_suspected flag."
      }
    },
    "/v0/messages/{message_id}/attachments/{index}": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "message_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "index",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Attachment bytes with its content type."
          }
        },
        "summary": "Download an attachment by index."
      }
    },
    "/v0/search": {
      "get": {
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching messages."
          }
        },
        "summary": "Full-text search across all of the account's messages."
      }
    },
    "/v0/threads/{thread_id}": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "thread_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Thread messages."
          }
        },
        "summary": "Get all messages in a thread, oldest first."
      }
    },
    "/v0/webhooks": {
      "get": {
        "responses": {
          "200": {
            "description": "Webhooks."
          }
        },
        "summary": "List webhooks."
      },
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "url": {
                    "format": "uri",
                    "type": "string"
                  }
                },
                "required": [
                  "url"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Webhook created; the secret is returned once."
          }
        },
        "summary": "Register a webhook for the message.received event. Deliveries are signed with HMAC-SHA256 in the x-botsinbox-signature header."
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "servers": [
    {
      "url": "https://api.botsinbox.com"
    }
  ]
}