{ "openapi": "3.1.0", "info": { "title": "Pirin.ai Founder Builder Studio API", "description": "API for AI agents to submit founder applications to Pirin.ai. Supports both OAuth-authenticated submissions and anonymous MCP submissions from ChatGPT.", "version": "1.2.0", "contact": { "email": "hello@pirin.ai", "url": "https://pirin.ai" } }, "servers": [ { "url": "https://pirin.ai/api", "description": "Production API" } ], "paths": { "/webhooks/resend/inbound": { "post": { "summary": "Receive inbound email webhook from Resend", "description": "Secure webhook endpoint for receiving inbound emails sent to *@pirin.ai addresses. Verifies Resend webhook signatures and stores email data in Supabase for future processing.", "operationId": "receiveInboundEmailWebhook", "tags": [ "Webhooks" ], "x-security-notes": { "authentication": "Webhook signature verification using Svix headers", "signature-headers": "Requires svix-id, svix-timestamp, svix-signature headers", "rate-limit": "Handled by Resend infrastructure" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "created_at", "data" ], "properties": { "type": { "type": "string", "enum": [ "email.received" ], "description": "Webhook event type" }, "created_at": { "type": "string", "format": "date-time", "description": "When Resend created the webhook event" }, "data": { "type": "object", "required": [ "email_id", "from", "to" ], "properties": { "email_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the email" }, "from": { "type": "string", "description": "Sender email in 'Name ' or 'email' format" }, "to": { "type": "array", "items": { "type": "string" }, "description": "Array of recipient email addresses" }, "cc": { "type": "array", "items": { "type": "string" }, "description": "Array of CC email addresses" }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "Array of BCC email addresses" }, "subject": { "type": "string", "description": "Email subject line" }, "text": { "type": "string", "description": "Plain text body (full content fetched from Resend API)" }, "html": { "type": "string", "description": "HTML body (full content fetched from Resend API)" }, "message_id": { "type": "string", "description": "RFC 2822 Message-ID header" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "content_disposition": { "type": "string" }, "content_id": { "type": "string" } } }, "description": "Attachment metadata array" }, "created_at": { "type": "string", "format": "date-time", "description": "When Resend received the email" } } } } }, "example": { "type": "email.received", "created_at": "2026-01-21T05:30:00.000Z", "data": { "email_id": "56761188-7520-42d8-8898-ff6fc54ce618", "from": "John Doe ", "to": [ "hello@pirin.ai" ], "subject": "Interested in your program", "text": "Hi, I'm interested in learning more about your founder programs...", "message_id": "", "created_at": "2026-01-21T05:29:45.000Z" } } } } }, "responses": { "200": { "description": "Webhook processed successfully - email stored in database", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "description": "Webhook signature verification failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "example": { "error": "Invalid signature", "message": "Webhook signature verification failed" } } } }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "example": { "error": "Invalid payload", "message": "Webhook payload does not match expected schema" } } } }, "500": { "description": "Internal server error - database or processing failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "example": { "error": "Processing failed", "message": "Failed to store email data" } } } } } } }, "/ai-agent/apply": { "get": { "summary": "Discover API capabilities", "description": "Get information about the AI agent API including required fields, authentication methods, and example requests.", "operationId": "getApiCapabilities", "tags": [ "Discovery" ], "responses": { "200": { "description": "API capabilities and documentation", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "endpoint": { "type": "string" }, "methods": { "type": "array", "items": { "type": "string" } }, "authentication": { "type": "object" }, "requiredFields": { "type": "array", "items": { "type": "string" } }, "optionalFields": { "type": "array", "items": { "type": "string" } } } } } } } } }, "post": { "summary": "Submit Ground Level application via AI agent (OAuth)", "description": "Submit a Ground Level application on behalf of an authenticated user. IMPORTANT: User must explicitly consent and the email must match the authenticated user's email. OAuth authentication via Supabase is required.", "operationId": "submitGroundLevelApplication", "tags": [ "Applications" ], "security": [ { "oauth2": [ "submit_application" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "authToken", "authProvider", "firstName", "lastName", "email", "projectName", "description", "currentStatus", "launchGoal", "biggestChallenge", "successLook", "aiAgent", "userConsent" ], "properties": { "authToken": { "type": "string", "description": "Supabase OAuth access token obtained via Google or GitHub authentication" }, "authProvider": { "type": "string", "enum": [ "google", "github" ], "description": "OAuth provider used for authentication" }, "firstName": { "type": "string", "description": "Founder's first name" }, "lastName": { "type": "string", "description": "Founder's last name" }, "email": { "type": "string", "format": "email", "description": "Founder's email address - MUST match the authenticated user's email" }, "projectName": { "type": "string", "description": "Name of the startup or product" }, "description": { "type": "string", "description": "Brief description of what problem the startup is solving" }, "currentStatus": { "type": "string", "enum": [ "idea", "wireframes", "prototype", "working" ], "description": "Current project status: idea, wireframes/mockups ready, 80% prototype, or working MVP" }, "launchGoal": { "type": "string", "format": "date", "description": "Target launch date (YYYY-MM-DD format)" }, "biggestChallenge": { "type": "string", "description": "The founder's biggest technical challenge right now" }, "successLook": { "type": "string", "description": "What success looks like for this founder" }, "aiAgent": { "type": "string", "description": "Name of the AI assistant submitting the application (e.g., ChatGPT, Claude, Grok)" }, "userConsent": { "type": "boolean", "description": "REQUIRED: Must be true. User must explicitly consent to AI agent submission." }, "startupProgram": { "type": "string", "description": "Optional: Startup accelerator or program (e.g., Founder Institute Austin 2026)" }, "directorName": { "type": "string", "description": "Optional: Name of program director or mentor who can vouch for the founder" }, "directorEmail": { "type": "string", "format": "email", "description": "Optional: Business email of the program director or mentor" } } }, "example": { "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "authProvider": "google", "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com", "projectName": "AI-powered CRM", "description": "Building an AI-first customer relationship management platform for small businesses", "currentStatus": "prototype", "launchGoal": "2026-04-01", "biggestChallenge": "Integrating with existing email providers and calendar systems", "successLook": "100 paying customers within 6 months of launch", "aiAgent": "ChatGPT", "userConsent": true, "startupProgram": "Founder Institute Austin 2026" } } } }, "responses": { "200": { "description": "Application submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "applicationId": { "type": "string", "format": "uuid", "description": "The unique ID of the submitted application" }, "userId": { "type": "string", "format": "uuid", "description": "The authenticated user's Supabase ID" }, "submittedVia": { "type": "string", "description": "Name of the AI agent that submitted the application" } } }, "example": { "success": true, "message": "Application submitted successfully", "applicationId": "123e4567-e89b-12d3-a456-426614174000", "userId": "987fcdeb-51a2-3bc4-d567-890123456789", "submittedVia": "ChatGPT" } } } }, "400": { "description": "Invalid request - missing required fields, user consent not given, or email mismatch", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "missing_field": { "value": { "error": "Missing required field: projectName" } }, "no_consent": { "value": { "error": "User consent required", "message": "The user must explicitly consent to having their application submitted by an AI agent" } }, "email_mismatch": { "value": { "error": "Email mismatch", "message": "Application email must match authenticated user email" } } } } } }, "401": { "description": "Authentication failed - invalid or expired OAuth token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "example": { "error": "Authentication failed", "message": "Invalid or expired authentication token" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "example": { "error": "Internal server error", "message": "Failed to process application. Please try again." } } } } } } }, "/mcp/submit-application": { "post": { "summary": "Submit anonymous MCP application from ChatGPT", "description": "Submit an application via MCP connector from ChatGPT. No OAuth required - requests must originate from ChatGPT/OpenAI infrastructure (validated via IP allowlist and User-Agent). Submissions are stored as anonymous guests.", "operationId": "submitMcpApplication", "tags": [ "MCP" ], "x-security-notes": { "authentication": "No OAuth - IP and User-Agent validation", "ip-validation": "Requests must originate from OpenAI/ChatGPT egress IP ranges (fetched from https://openai.com/chatgpt-actions.json)", "user-agent": "Must include 'ChatGPT', 'OpenAI', or 'GPTBot' in User-Agent header", "rate-limit": "100 requests/minute per IP (planned)" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email", "details", "message" ], "properties": { "name": { "type": "string", "description": "Applicant's full name" }, "email": { "type": "string", "format": "email", "description": "Applicant's email address" }, "details": { "type": "string", "description": "Application level (ground or next)" }, "message": { "type": "string", "description": "Application message and details" } } }, "example": { "name": "Jane Doe", "email": "jane@example.com", "details": "ground", "message": "I want to join the Ground Level program to build my AI-powered CRM" } } } }, "responses": { "200": { "description": "Application submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "success": true, "message": "Application submitted successfully" } } } }, "400": { "description": "Invalid request - missing required fields or invalid data", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "Invalid request" } } } }, "403": { "description": "Access denied - request blocked by security validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "invalid_ip": { "value": { "error": "Access denied: Invalid origin IP" } }, "invalid_ua": { "value": { "error": "Access denied: Invalid User-Agent" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "Failed to submit application" } } } } } } }, "/contact": { "post": { "summary": "Submit contact form inquiry", "description": "Submit a general inquiry, technical question, partnership request, or pricing question. This endpoint is public and requires no authentication.", "operationId": "submitContactForm", "tags": [ "Public Forms" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email", "subject", "message" ], "properties": { "name": { "type": "string", "description": "Contact's full name" }, "email": { "type": "string", "format": "email", "description": "Contact's email address" }, "subject": { "type": "string", "enum": [ "general", "pricing", "technical", "partnership", "other" ], "description": "Inquiry subject category" }, "message": { "type": "string", "description": "Inquiry message" }, "phone": { "type": "string", "maxLength": 32, "description": "Optional mobile number. Omit or send an empty string when the visitor did not provide one. A provided number is stored as E.164. Ten-digit input is treated as US +1. An invalid number returns 400." }, "sms_consent": { "type": "boolean", "description": "True only when the visitor checked the SMS consent box and provided a phone number. Omitted or false means no consent. True with a missing or blank phone returns 400. The server records the consent time." } } }, "example": { "name": "John Smith", "email": "john@company.com", "subject": "technical", "message": "I have questions about integrating AI into our workflow", "phone": "", "sms_consent": false } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "400": { "description": "Invalid request. A required field is missing, SMS consent was set without a phone number, or the phone number is invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "name is required" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "Failed to send message. Please try again." } } } } } } }, "/workshop-waitlist": { "post": { "summary": "Join executive AI workshop waitlist", "description": "Request invitation to executive AI workshops in downtown Austin, TX. Half-day hands-on sessions limited to 20 decision-makers. Requires work email (no free email providers). AI agents should obtain explicit user consent before submission.", "operationId": "joinWorkshopWaitlist", "tags": [ "Public Forms" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email", "company", "title", "company_size" ], "properties": { "name": { "type": "string", "description": "Full name of executive" }, "email": { "type": "string", "format": "email", "description": "Work email address (no Gmail, Yahoo, Hotmail, etc.)" }, "company": { "type": "string", "description": "Company name" }, "title": { "type": "string", "description": "Job title (e.g., CEO, VP of Operations, CTO)" }, "company_size": { "type": "string", "enum": [ "10-50", "51-200", "201-1000", "1000+" ], "description": "Company size range" }, "interest_areas": { "type": "array", "items": { "type": "string", "enum": [ "Agentic Workflows", "AI Copilots for Teams", "On-Premise AI", "AI Strategy", "Custom Integrations", "AI Governance & Safety" ] }, "description": "Topics of interest (optional, can be empty array)" }, "message": { "type": "string", "description": "Optional: Biggest AI challenge or opportunity in your business" } } }, "example": { "name": "Sarah Johnson", "email": "sarah@acmecorp.com", "company": "Acme Corp", "title": "VP of Operations", "company_size": "51-200", "interest_areas": [ "Agentic Workflows", "AI Copilots for Teams" ], "message": "We handle 500+ support tickets/day and want to automate triage" } } } }, "responses": { "200": { "description": "Successfully added to waitlist", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "400": { "description": "Invalid request - missing required fields or free email provider", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "missing_field": { "value": { "error": "company is required" } }, "free_email": { "value": { "error": "Please use your work email address." } } } } } }, "409": { "description": "Email already on waitlist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "This email is already on the waitlist. We will be in touch." } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "Something went wrong. Please try again later." } } } } } } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth 2.0 authentication via Supabase. Users authenticate with Google or GitHub.", "flows": { "authorizationCode": { "authorizationUrl": "https://pirin.ai/api/auth/authorize", "tokenUrl": "https://pirin.ai/api/auth/token", "scopes": { "submit_application": "Submit founder applications on behalf of authenticated user" } } } } } } }