{ "openapi": "3.1.0", "info": { "title": "Nudgen Developer API", "version": "1.0.0", "description": "REST API for managing Nudgen contacts, campaigns, brand settings, and AI email drafts with Personal Access Token authentication." }, "servers": [ { "url": "https://nudgen.net", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Identity" }, { "name": "Contacts" }, { "name": "Campaigns" }, { "name": "Brand settings" }, { "name": "AI" } ], "paths": { "/api/v1/user/me": { "get": { "tags": ["Identity"], "summary": "Get current user", "description": "Returns the authenticated user for the provided Personal Access Token.", "operationId": "getCurrentUser", "responses": { "200": { "description": "Authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/teams": { "get": { "tags": ["Identity"], "summary": "List workspaces", "description": "Lists workspaces available to the token owner and identifies the active workspace.", "operationId": "listTeams", "responses": { "200": { "description": "Workspace list", "content": { "application/json": { "schema": { "type": "object", "properties": { "teams": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "activeTeam": { "anyOf": [ { "$ref": "#/components/schemas/Team" }, { "type": "null" } ] }, "isAdmin": { "type": "boolean" }, "canCreateTeam": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/contacts": { "get": { "tags": ["Contacts"], "summary": "List contacts", "description": "Lists contacts in the active workspace. Contact PII is decrypted in the authorized response.", "operationId": "listContacts", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search by decrypted contact email." }, { "name": "tags", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated tags." }, { "name": "status", "in": "query", "schema": { "type": "string", "example": "active,unsubscribed" }, "description": "Comma-separated statuses." } ], "responses": { "200": { "description": "Contact list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/contacts/add": { "post": { "tags": ["Contacts"], "summary": "Create contact", "description": "Creates one contact in the active workspace.", "operationId": "createContact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactRequest" }, "example": { "email": "nathan@example.com", "name": "Nathan Nguyen", "tags": ["api-test"] } } } }, "responses": { "200": { "description": "Contact created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "contact": { "type": "object", "properties": { "id": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/contacts/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "tags": ["Contacts"], "summary": "Get contact", "operationId": "getContact", "responses": { "200": { "description": "Contact", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "$ref": "#/components/schemas/Contact" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": ["Contacts"], "summary": "Update contact", "operationId": "updateContact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactRequest" } } } }, "responses": { "200": { "description": "Contact updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": ["Contacts"], "summary": "Delete contact", "operationId": "deleteContact", "responses": { "200": { "description": "Contact deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/campaigns": { "get": { "tags": ["Campaigns"], "summary": "List campaigns", "description": "Lists campaigns in the active workspace.", "operationId": "listCampaigns", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string", "example": "one-time,drip" } }, { "name": "status", "in": "query", "schema": { "type": "string", "example": "draft,scheduled" } } ], "responses": { "200": { "description": "Campaign list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignListResponse" } } } } } }, "post": { "tags": ["Campaigns"], "summary": "Create campaign", "description": "Creates a campaign draft, scheduled campaign, or immediate send when `sendNow` is true.", "operationId": "createCampaign", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignRequest" }, "example": { "name": "API launch test", "goal": "Invite contacts to try Nudgen.", "subject": "Try Nudgen", "html": "

Ready to launch smarter email?

", "link": "https://nudgen.net", "audienceType": "manual", "audienceContactIds": ["contact_id"] } } } }, "responses": { "200": { "description": "Campaign created", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "$ref": "#/components/schemas/Campaign" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/campaigns/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "tags": ["Campaigns"], "summary": "Get campaign", "operationId": "getCampaign", "responses": { "200": { "description": "Campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "$ref": "#/components/schemas/Campaign" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": ["Campaigns"], "summary": "Update campaign", "operationId": "updateCampaign", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCampaignRequest" } } } }, "responses": { "200": { "description": "Campaign updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/campaigns/{id}/launch": { "post": { "tags": ["Campaigns"], "summary": "Launch campaign", "description": "Launches a campaign now or schedules it for a future time.", "operationId": "launchCampaign", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchCampaignRequest" }, "example": { "sendNow": false, "scheduledAt": "2026-05-21T06:46:52.128Z" } } } }, "responses": { "200": { "description": "Campaign scheduled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchCampaignResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/campaigns/{id}/stats": { "get": { "tags": ["Campaigns"], "summary": "Get campaign stats", "operationId": "getCampaignStats", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Campaign stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "$ref": "#/components/schemas/CampaignStats" } } } } } } } } }, "/api/v1/settings/brand": { "get": { "tags": ["Brand settings"], "summary": "Get brand settings", "operationId": "getBrandSettings", "responses": { "200": { "description": "Brand settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandSettings" } } } } } }, "patch": { "tags": ["Brand settings"], "summary": "Update brand settings", "operationId": "updateBrandSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBrandSettingsRequest" } } } }, "responses": { "200": { "description": "Updated brand settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandSettings" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/ai/generate": { "post": { "tags": ["AI"], "summary": "Generate email draft", "description": "Generates an email subject and HTML draft from campaign context and the active workspace brand settings.", "operationId": "generateEmailDraft", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateEmailDraftRequest" }, "example": { "campaignGoal": "Write a short retention email inviting users to try Nudgen.", "link": "https://nudgen.net", "personalizationMode": "off" } } } }, "responses": { "200": { "description": "Generated draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDraft" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "PAT", "description": "Personal Access Token created from Settings -> API Keys." } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } }, "responses": { "BadRequest": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Missing, invalid, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "The workspace cannot perform this write action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" } } }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "Team": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "role": { "type": "string" }, "isBetaTester": { "type": "boolean" } } }, "Contact": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "phone": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": ["active", "unsubscribed", "bounced"] }, "tags": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" } } }, "ContactListResponse": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "CreateContactRequest": { "type": "object", "required": ["email", "name"], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "phone": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "UpdateContactRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "phone": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["active", "unsubscribed", "bounced"] } } }, "Campaign": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": ["one-time", "drip"] }, "status": { "type": "string", "enum": ["draft", "scheduled", "sending", "sent", "stopped"] }, "subject": { "type": "string" }, "scheduledAt": { "type": ["string", "null"], "format": "date-time" }, "sentAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CampaignListResponse": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "CreateCampaignRequest": { "type": "object", "required": ["name", "goal", "subject", "html", "link"], "properties": { "name": { "type": "string" }, "goal": { "type": "string" }, "subject": { "type": "string" }, "html": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "audienceType": { "type": "string", "enum": ["all", "tags", "manual"], "default": "all" }, "audienceTags": { "type": "array", "items": { "type": "string" } }, "audienceContactIds": { "type": "array", "items": { "type": "string" } }, "sendNow": { "type": "boolean", "default": false }, "scheduledAt": { "type": "string", "format": "date-time" }, "personalizationMode": { "type": "string", "enum": ["off", "lead_description_intro"], "default": "off" } } }, "UpdateCampaignRequest": { "type": "object", "properties": { "name": { "type": "string" }, "goal": { "type": "string" }, "subject": { "type": "string" }, "html": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "audienceType": { "type": "string", "enum": ["all", "tags", "manual"] }, "audienceTags": { "type": "array", "items": { "type": "string" } }, "audienceContactIds": { "type": "array", "items": { "type": "string" } }, "sendNow": { "type": "boolean" }, "scheduledAt": { "type": "string", "format": "date-time" }, "personalizationMode": { "type": "string", "enum": ["off", "lead_description_intro"] } } }, "LaunchCampaignRequest": { "type": "object", "properties": { "sendNow": { "type": "boolean", "default": true }, "scheduledAt": { "type": "string", "format": "date-time" } } }, "LaunchCampaignResponse": { "type": "object", "properties": { "campaign": { "$ref": "#/components/schemas/Campaign" }, "launched": { "type": "boolean" }, "delayMs": { "type": "integer" } } }, "CampaignStats": { "type": "object", "properties": { "totalSent": { "type": "integer" }, "totalDelivered": { "type": "integer" }, "totalOpens": { "type": "integer" }, "totalClicks": { "type": "integer" }, "ctr": { "type": "number" }, "totalFailed": { "type": "integer" }, "totalSpamComplaints": { "type": "integer" }, "totalHardBounces": { "type": "integer" }, "totalSoftBounces": { "type": "integer" } } }, "BrandSettings": { "type": "object", "properties": { "brandName": { "type": ["string", "null"] }, "brandDescription": { "type": ["string", "null"] }, "brandEmail": { "type": ["string", "null"], "format": "email" }, "websiteUrl": { "type": ["string", "null"], "format": "uri" }, "emailLanguage": { "type": ["string", "null"] }, "logoUrl": { "type": ["string", "null"], "format": "uri" }, "brandDesignSystem": { "type": ["object", "null"], "additionalProperties": true }, "brandDesignMarkdown": { "type": ["string", "null"] } } }, "UpdateBrandSettingsRequest": { "type": "object", "properties": { "brandName": { "type": ["string", "null"] }, "brandDescription": { "type": ["string", "null"] }, "brandEmail": { "type": ["string", "null"], "format": "email" }, "websiteUrl": { "type": ["string", "null"], "format": "uri" }, "emailLanguage": { "type": ["string", "null"] }, "logoUrl": { "type": ["string", "null"], "format": "uri" }, "brandDesignSystem": { "type": ["object", "null"], "additionalProperties": true } } }, "GenerateEmailDraftRequest": { "type": "object", "required": ["campaignGoal"], "properties": { "campaignGoal": { "type": "string" }, "context": { "type": ["string", "null"] }, "link": { "type": ["string", "null"], "format": "uri" }, "templateId": { "type": ["string", "null"] }, "templateHtml": { "type": ["string", "null"] }, "templateSubject": { "type": ["string", "null"] }, "autoSelectTemplate": { "type": "boolean" }, "personalizationMode": { "type": "string", "enum": ["off", "lead_description_intro"], "default": "off" } } }, "EmailDraft": { "type": "object", "properties": { "subject": { "type": "string" }, "html": { "type": "string" }, "generationMode": { "type": "string" } } } } } }