{ "openapi": "3.1.0", "info": { "title": "Nevola Engine API", "version": "1.0.0", "summary": "Personalization infrastructure for digital content brands.", "description": "The Nevola Engine API creates profile context, reads temporal-contextual signals, and generates personalized content for subscription content, edtech, and wellness products.\nThe API uses JSON over HTTPS, bearer API keys, stable resource identifiers, and consistent error envelopes.\n", "contact": { "name": "Nevola Group", "email": "contact@nevolagroup.com", "url": "https://nevolagroup.com/" } }, "servers": [ { "url": "https://api.nevolagroup.com/v1", "description": "Production" }, { "url": "https://api.sandbox.nevolagroup.com/v1", "description": "Sandbox" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Profiles", "description": "Create, update, retrieve, and remove personalization context handles." }, { "name": "Personalize", "description": "Generate personalized content synchronously or start asynchronous sequence runs." }, { "name": "Signals", "description": "Read derived temporal-contextual signals and the definitions behind them." }, { "name": "Webhooks", "description": "Register endpoints that receive asynchronous delivery events." } ], "paths": { "/profiles": { "post": { "tags": [ "Profiles" ], "operationId": "createProfile", "summary": "Create a profile", "description": "Creates a profile used as the context handle for personalization calls.\nStore only the profile ID in your application; Nevola stores the external user reference and attributes needed to compute content context.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileCreate" }, "examples": { "contentSubscriber": { "summary": "Subscription content profile", "value": { "external_user_id": "usr_9b1f0c8a72", "locale": "en-GB", "attributes": { "plan": "pro", "audience_segment": "editorial_manager", "lifecycle_stage": "activated", "content_preferences": { "format": "newsletter", "cadence": "weekday" } } } } } } } }, "responses": { "201": { "description": "Profile created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" }, "examples": { "created": { "value": { "id": "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA", "object": "profile", "external_user_id": "usr_9b1f0c8a72", "locale": "en-GB", "attributes": { "plan": "pro", "audience_segment": "editorial_manager", "lifecycle_stage": "activated", "content_preferences": { "format": "newsletter", "cadence": "weekday" } }, "created_at": "2025-02-14T10:12:42Z", "updated_at": "2025-02-14T10:12:42Z", "deleted_at": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/profiles/{profile_id}": { "get": { "tags": [ "Profiles" ], "operationId": "retrieveProfile", "summary": "Retrieve a profile", "description": "Retrieves a profile by its Nevola profile ID.\nUse this endpoint to inspect the current locale and attributes attached to a personalization context handle.\n", "parameters": [ { "$ref": "#/components/parameters/ProfileId" } ], "responses": { "200": { "description": "Profile retrieved.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" }, "examples": { "retrieved": { "value": { "id": "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA", "object": "profile", "external_user_id": "usr_9b1f0c8a72", "locale": "en-GB", "attributes": { "plan": "pro", "audience_segment": "editorial_manager", "lifecycle_stage": "activated" }, "created_at": "2025-02-14T10:12:42Z", "updated_at": "2025-02-14T10:14:06Z", "deleted_at": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Profiles" ], "operationId": "updateProfile", "summary": "Update profile attributes", "description": "Updates mutable fields on a profile.\nAttribute updates replace only the provided keys; omitted keys remain unchanged.\n", "parameters": [ { "$ref": "#/components/parameters/ProfileId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileUpdate" }, "examples": { "updateLifecycle": { "summary": "Update lifecycle and preferences", "value": { "locale": "en", "attributes": { "lifecycle_stage": "retained", "content_preferences": { "format": "audio_script", "cadence": "weekly" } } } } } } } }, "responses": { "200": { "description": "Profile updated.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" }, "examples": { "updated": { "value": { "id": "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA", "object": "profile", "external_user_id": "usr_9b1f0c8a72", "locale": "en", "attributes": { "plan": "pro", "audience_segment": "editorial_manager", "lifecycle_stage": "retained", "content_preferences": { "format": "audio_script", "cadence": "weekly" } }, "created_at": "2025-02-14T10:12:42Z", "updated_at": "2025-02-14T10:18:09Z", "deleted_at": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Profiles" ], "operationId": "deleteProfile", "summary": "Delete a profile", "description": "Deletes a profile for right-to-erasure workflows.\nThe profile can no longer be used in personalization requests after deletion completes.\n", "parameters": [ { "$ref": "#/components/parameters/ProfileId" } ], "responses": { "200": { "description": "Profile deleted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedObject" }, "examples": { "deleted": { "value": { "id": "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA", "object": "profile", "deleted": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/personalize/content": { "post": { "tags": [ "Personalize" ], "operationId": "personalizeContent", "summary": "Generate personalized content", "description": "Generates one content item synchronously for a profile and template.\nUse this endpoint when your product needs an immediate response inside a request path, such as a dashboard module, newsletter block, or course step.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalizeContentRequest" }, "examples": { "newsletter": { "summary": "Newsletter block", "value": { "profile_id": "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA", "content_type": "newsletter", "template_id": "tmpl_newsletter_retention_v3", "variant_strategy": "stable" } } } } } }, "responses": { "200": { "description": "Personalized content generated.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalizeContentResponse" }, "examples": { "newsletter": { "value": { "id": "pc_01HXY8A6P1Z0M6CB7J81KXW2QP", "object": "personalized_content", "profile_id": "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA", "content_type": "newsletter", "template_id": "tmpl_newsletter_retention_v3", "template_version": 3, "variant_strategy": "stable", "generated_at": "2025-02-14T10:22:31Z", "content": { "subject": "Your Friday plan for product-led onboarding", "body": "Start with the two accounts that have not completed setup. The short path today is one reminder, one example, and one checkpoint.", "cta_label": "Open checklist" }, "signals": [ { "key": "weekday_window", "value": "friday", "value_type": "string", "calculation_version": "2025-02-01", "computed_at": "2025-02-14T10:22:30Z" }, { "key": "cadence_fit", "value": "weekday", "value_type": "string", "calculation_version": "2025-02-01", "computed_at": "2025-02-14T10:22:30Z" } ], "usage": { "input_units": 812, "output_units": 96 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/personalize/sequence": { "post": { "tags": [ "Personalize" ], "operationId": "createPersonalizeSequenceRun", "summary": "Start a sequence run", "description": "Starts asynchronous generation for an ordered sequence of personalized content items.\nUse this endpoint for multi-step flows that can finish outside the original request, then receive completion status by webhook or polling.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalizeSequenceRequest" }, "examples": { "onboardingSequence": { "summary": "Course sequence", "value": { "profile_id": "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA", "sequence_id": "seq_course_onboarding_v2", "callback_url": "https://example.edu/webhooks/nevola" } } } } } }, "responses": { "202": { "description": "Sequence run accepted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceRun" }, "examples": { "accepted": { "value": { "id": "run_01HXY8KM47PF6WMH3BBV2YJ9KQ", "object": "sequence_run", "sequence_id": "seq_course_onboarding_v2", "profile_id": "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA", "status": "queued", "callback_url": "https://example.edu/webhooks/nevola", "items": [], "created_at": "2025-02-14T10:24:12Z", "updated_at": "2025-02-14T10:24:12Z", "completed_at": null, "error": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/personalize/sequence/{sequence_run_id}": { "get": { "tags": [ "Personalize" ], "operationId": "retrievePersonalizeSequenceRun", "summary": "Retrieve sequence status", "description": "Retrieves the current status of an asynchronous sequence run.\nPoll this endpoint when webhook delivery is not available, or use it to reconcile local job state after receiving a webhook event.\n", "parameters": [ { "$ref": "#/components/parameters/SequenceRunId" } ], "responses": { "200": { "description": "Sequence run retrieved.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceRun" }, "examples": { "delivered": { "value": { "id": "run_01HXY8KM47PF6WMH3BBV2YJ9KQ", "object": "sequence_run", "sequence_id": "seq_course_onboarding_v2", "profile_id": "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA", "status": "delivered", "callback_url": "https://example.edu/webhooks/nevola", "items": [ { "id": "pc_01HXY8NVQ4KDVK758G9BVP2T6S", "content_type": "course_step", "template_id": "tmpl_course_step_v4", "template_version": 4, "position": 1 }, { "id": "pc_01HXY8NYJ1XQ7N4F9KQ0V82GZP", "content_type": "checkpoint", "template_id": "tmpl_checkpoint_v2", "template_version": 2, "position": 2 } ], "created_at": "2025-02-14T10:24:12Z", "updated_at": "2025-02-14T10:24:44Z", "completed_at": "2025-02-14T10:24:44Z", "error": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/signals/temporal/{profile_id}": { "get": { "tags": [ "Signals" ], "operationId": "retrieveTemporalSignals", "summary": "Retrieve temporal signals for a profile", "description": "Retrieves the current derived temporal-contextual signals for a profile.\nResults are deterministic for the profile, timestamp, locale, and active signal definition versions used at computation time.\n", "parameters": [ { "$ref": "#/components/parameters/ProfileId" }, { "name": "at", "in": "query", "required": false, "description": "Optional ISO 8601 timestamp used as the computation time. Defaults to request time.", "schema": { "type": "string", "format": "date-time" }, "example": "2025-02-14T10:30:00Z" } ], "responses": { "200": { "description": "Temporal signals retrieved.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "object", "profile_id", "computed_at", "data" ], "properties": { "object": { "type": "string", "const": "temporal_signal_list" }, "profile_id": { "type": "string" }, "computed_at": { "type": "string", "format": "date-time" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemporalSignal" } } } }, "examples": { "current": { "value": { "object": "temporal_signal_list", "profile_id": "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA", "computed_at": "2025-02-14T10:30:00Z", "data": [ { "key": "weekday_window", "value": "friday", "value_type": "string", "calculation_version": "2025-02-01", "computed_at": "2025-02-14T10:30:00Z" }, { "key": "local_part_of_day", "value": "morning", "value_type": "string", "calculation_version": "2025-02-01", "computed_at": "2025-02-14T10:30:00Z" }, { "key": "content_cadence_match", "value": true, "value_type": "boolean", "calculation_version": "2025-02-01", "computed_at": "2025-02-14T10:30:00Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/signals/definitions": { "get": { "tags": [ "Signals" ], "operationId": "listSignalDefinitions", "summary": "List signal definitions", "description": "Lists available signal definitions for your workspace.\nDefinitions describe value type, version, and supported content types so template authors can reference signals safely.\n", "parameters": [ { "name": "content_type", "in": "query", "required": false, "description": "Filter definitions by supported content type.", "schema": { "$ref": "#/components/schemas/ContentType" }, "example": "newsletter" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Signal definitions listed.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SignalDefinition" } }, "has_more": { "type": "boolean" } } }, "examples": { "definitions": { "value": { "object": "list", "data": [ { "key": "weekday_window", "label": "Weekday window", "description": "Local weekday bucket computed from request time and profile locale.", "value_type": "string", "version": "2025-02-01", "content_types": [ "newsletter", "daily_drop", "course_step" ] }, { "key": "content_cadence_match", "label": "Content cadence match", "description": "Boolean indicating whether the current request time matches the profile's preferred content cadence.", "value_type": "boolean", "version": "2025-02-01", "content_types": [ "newsletter", "audio_script" ] } ], "has_more": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/webhooks": { "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Register a webhook", "description": "Registers an HTTPS endpoint to receive asynchronous events from Nevola Engine.\nWebhooks are workspace-scoped and can subscribe to one or more event types.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" }, "examples": { "sequenceEvents": { "summary": "Sequence completion events", "value": { "url": "https://example.com/api/nevola/events", "events": [ "personalize.sequence.completed", "personalize.sequence.failed" ] } } } } } }, "responses": { "201": { "description": "Webhook registered.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "examples": { "registered": { "value": { "id": "wh_01HXY95P8JH6B6F0AJQS4V78QT", "object": "webhook", "url": "https://example.com/api/nevola/events", "events": [ "personalize.sequence.completed", "personalize.sequence.failed" ], "active": true, "created_at": "2025-02-14T10:34:18Z", "updated_at": "2025-02-14T10:34:18Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "List webhooks", "description": "Lists registered webhooks for the workspace associated with the API key.\nUse this endpoint during deployment checks or to reconcile webhook configuration in your admin system.\n", "parameters": [ { "name": "active", "in": "query", "required": false, "description": "Filter by active state.", "schema": { "type": "boolean" }, "example": true }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Webhooks listed.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "has_more": { "type": "boolean" } } }, "examples": { "list": { "value": { "object": "list", "data": [ { "id": "wh_01HXY95P8JH6B6F0AJQS4V78QT", "object": "webhook", "url": "https://example.com/api/nevola/events", "events": [ "personalize.sequence.completed", "personalize.sequence.failed" ], "active": true, "created_at": "2025-02-14T10:34:18Z", "updated_at": "2025-02-14T10:34:18Z" } ], "has_more": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/webhooks/{webhook_id}": { "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Remove a webhook", "description": "Removes a registered webhook from the workspace.\nEvents already queued for delivery may still be sent for a short time after removal.\n", "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "description": "Webhook removed.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedObject" }, "examples": { "deleted": { "value": { "id": "wh_01HXY95P8JH6B6F0AJQS4V78QT", "object": "webhook", "deleted": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Use a Nevola API key as a bearer token. Live keys start with `nev_live_`; sandbox keys start with `nev_test_`." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safely retrying POST requests. Store one key per logical operation for at least 24 hours.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "example": "idem_01HXY83CR0M3KD8X3K7E1QPK3H" }, "ProfileId": { "name": "profile_id", "in": "path", "required": true, "description": "Unique profile identifier.", "schema": { "type": "string", "pattern": "^prof_[0-9A-HJKMNP-TV-Z]{26}$" }, "example": "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA" }, "SequenceRunId": { "name": "sequence_run_id", "in": "path", "required": true, "description": "Unique sequence run identifier.", "schema": { "type": "string", "pattern": "^run_[0-9A-HJKMNP-TV-Z]{26}$" }, "example": "run_01HXY8KM47PF6WMH3BBV2YJ9KQ" }, "WebhookId": { "name": "webhook_id", "in": "path", "required": true, "description": "Unique webhook identifier.", "schema": { "type": "string", "pattern": "^wh_[0-9A-HJKMNP-TV-Z]{26}$" }, "example": "wh_01HXY95P8JH6B6F0AJQS4V78QT" }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "Number of objects to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current rate limit window.", "schema": { "type": "integer" }, "example": 1200 }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current rate limit window.", "schema": { "type": "integer" }, "example": 1193 }, "X-RateLimit-Reset": { "description": "Unix timestamp when the current rate limit window resets.", "schema": { "type": "integer" }, "example": 1739530800 } }, "schemas": { "Locale": { "type": "string", "description": "BCP 47 locale used for content and temporal calculations.", "enum": [ "en", "en-GB", "de", "fr", "pt-BR" ], "examples": [ "en-GB" ] }, "ContentType": { "type": "string", "description": "Content format requested from the template registry.", "enum": [ "newsletter", "audio_script", "daily_drop", "course_step", "checkpoint" ], "examples": [ "newsletter" ] }, "AttributeMap": { "type": "object", "description": "Customer-defined profile attributes. Avoid raw PII; use stable internal identifiers and product context.", "additionalProperties": { "type": [ "string", "number", "integer", "boolean", "object", "array", "null" ] }, "examples": [ { "plan": "pro", "audience_segment": "editorial_manager", "lifecycle_stage": "activated" } ] }, "Profile": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "external_user_id", "locale", "attributes", "created_at", "updated_at", "deleted_at" ], "properties": { "id": { "type": "string", "pattern": "^prof_[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA" ] }, "object": { "type": "string", "const": "profile" }, "external_user_id": { "type": "string", "description": "Your stable end-user reference. Use a hash or opaque identifier.", "minLength": 1, "maxLength": 128, "examples": [ "usr_9b1f0c8a72" ] }, "locale": { "$ref": "#/components/schemas/Locale" }, "attributes": { "$ref": "#/components/schemas/AttributeMap" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProfileCreate": { "type": "object", "additionalProperties": false, "required": [ "external_user_id", "locale" ], "properties": { "external_user_id": { "type": "string", "description": "Your stable end-user reference. Use a hash or opaque identifier.", "minLength": 1, "maxLength": 128, "examples": [ "usr_9b1f0c8a72" ] }, "locale": { "$ref": "#/components/schemas/Locale" }, "attributes": { "$ref": "#/components/schemas/AttributeMap" } } }, "ProfileUpdate": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "locale": { "$ref": "#/components/schemas/Locale" }, "attributes": { "$ref": "#/components/schemas/AttributeMap" } } }, "PersonalizeContentRequest": { "type": "object", "additionalProperties": false, "required": [ "profile_id", "content_type", "template_id", "variant_strategy" ], "properties": { "profile_id": { "type": "string", "pattern": "^prof_[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA" ] }, "content_type": { "$ref": "#/components/schemas/ContentType" }, "template_id": { "type": "string", "description": "Template registry identifier.", "minLength": 3, "maxLength": 128, "examples": [ "tmpl_newsletter_retention_v3" ] }, "variant_strategy": { "type": "string", "description": "Variant selection mode for the template call.", "enum": [ "stable", "latest", "explore" ], "examples": [ "stable" ] } } }, "PersonalizeContentResponse": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "profile_id", "content_type", "template_id", "template_version", "variant_strategy", "generated_at", "content", "signals", "usage" ], "properties": { "id": { "type": "string", "pattern": "^pc_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "personalized_content" }, "profile_id": { "type": "string", "pattern": "^prof_[0-9A-HJKMNP-TV-Z]{26}$" }, "content_type": { "$ref": "#/components/schemas/ContentType" }, "template_id": { "type": "string" }, "template_version": { "type": "integer", "minimum": 1 }, "variant_strategy": { "type": "string", "enum": [ "stable", "latest", "explore" ] }, "generated_at": { "type": "string", "format": "date-time" }, "content": { "type": "object", "description": "Template-shaped content payload.", "additionalProperties": true }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/TemporalSignal" } }, "usage": { "type": "object", "additionalProperties": false, "required": [ "input_units", "output_units" ], "properties": { "input_units": { "type": "integer", "minimum": 0 }, "output_units": { "type": "integer", "minimum": 0 } } } } }, "PersonalizeSequenceRequest": { "type": "object", "additionalProperties": false, "required": [ "profile_id", "sequence_id" ], "properties": { "profile_id": { "type": "string", "pattern": "^prof_[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA" ] }, "sequence_id": { "type": "string", "description": "Registry identifier for an ordered sequence of templates.", "minLength": 3, "maxLength": 128, "examples": [ "seq_course_onboarding_v2" ] }, "callback_url": { "type": [ "string", "null" ], "format": "uri", "description": "Optional HTTPS URL that receives completion or failure events for this run.", "examples": [ "https://example.edu/webhooks/nevola" ] } } }, "SequenceRun": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "sequence_id", "profile_id", "status", "callback_url", "items", "created_at", "updated_at", "completed_at", "error" ], "properties": { "id": { "type": "string", "pattern": "^run_[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "run_01HXY8KM47PF6WMH3BBV2YJ9KQ" ] }, "object": { "type": "string", "const": "sequence_run" }, "sequence_id": { "type": "string" }, "profile_id": { "type": "string", "pattern": "^prof_[0-9A-HJKMNP-TV-Z]{26}$" }, "status": { "type": "string", "enum": [ "queued", "processing", "delivered", "failed", "canceled" ] }, "callback_url": { "type": [ "string", "null" ], "format": "uri" }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "content_type", "template_id", "template_version", "position" ], "properties": { "id": { "type": "string", "pattern": "^pc_[0-9A-HJKMNP-TV-Z]{26}$" }, "content_type": { "$ref": "#/components/schemas/ContentType" }, "template_id": { "type": "string" }, "template_version": { "type": "integer", "minimum": 1 }, "position": { "type": "integer", "minimum": 1 } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "null" } ] } } }, "TemporalSignal": { "type": "object", "additionalProperties": false, "required": [ "key", "value", "value_type", "calculation_version", "computed_at" ], "properties": { "key": { "type": "string", "description": "Stable signal key used by templates.", "examples": [ "weekday_window" ] }, "value": { "description": "Computed signal value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "object" }, { "type": "array" } ] }, "value_type": { "type": "string", "enum": [ "string", "number", "integer", "boolean", "object", "array" ] }, "calculation_version": { "type": "string", "description": "Version of the signal definition used to compute the value.", "examples": [ "2025-02-01" ] }, "computed_at": { "type": "string", "format": "date-time" } } }, "SignalDefinition": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "description", "value_type", "version", "content_types" ], "properties": { "key": { "type": "string", "examples": [ "weekday_window" ] }, "label": { "type": "string", "examples": [ "Weekday window" ] }, "description": { "type": "string", "examples": [ "Local weekday bucket computed from request time and profile locale." ] }, "value_type": { "type": "string", "enum": [ "string", "number", "integer", "boolean", "object", "array" ] }, "version": { "type": "string", "examples": [ "2025-02-01" ] }, "content_types": { "type": "array", "items": { "$ref": "#/components/schemas/ContentType" } } } }, "WebhookCreate": { "type": "object", "additionalProperties": false, "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint that receives event payloads.", "examples": [ "https://example.com/api/nevola/events" ] }, "events": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "Webhook": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "url", "events", "active", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^wh_[0-9A-HJKMNP-TV-Z]{26}$", "examples": [ "wh_01HXY95P8JH6B6F0AJQS4V78QT" ] }, "object": { "type": "string", "const": "webhook" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookEvent": { "type": "string", "enum": [ "personalize.content.created", "personalize.sequence.completed", "personalize.sequence.failed", "profile.deleted" ] }, "DeletedObject": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "deleted" ], "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean", "const": true } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "request_id", "doc_url" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code.", "examples": [ "invalid_request" ] }, "message": { "type": "string", "description": "Human-readable error message.", "examples": [ "The profile_id parameter is required." ] }, "request_id": { "type": "string", "description": "Request identifier for support and logs.", "examples": [ "req_01HXY9D9RZ6PKA7A4N52R8T1CQ" ] }, "doc_url": { "type": "string", "format": "uri", "description": "Documentation URL for the error.", "examples": [ "https://docs.nevolagroup.com/errors/invalid_request" ] } } } }, "responses": { "BadRequest": { "description": "Bad request.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalidRequest": { "value": { "code": "invalid_request", "message": "The request body must be valid JSON.", "request_id": "req_01HXY9D9RZ6PKA7A4N52R8T1CQ", "doc_url": "https://docs.nevolagroup.com/errors/invalid_request" } } } } } }, "Unauthorized": { "description": "Authentication failed or no API key was provided.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "code": "authentication_required", "message": "Provide a valid Nevola API key in the Authorization header.", "request_id": "req_01HXY9F3TW5N6SBK27QZB8E7NA", "doc_url": "https://docs.nevolagroup.com/errors/authentication_required" } } } } } }, "Forbidden": { "description": "The API key does not have access to the requested resource.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "denied": { "value": { "code": "access_denied", "message": "This API key cannot access the requested workspace resource.", "request_id": "req_01HXY9G72HDEH6R7N4M41M3QK9", "doc_url": "https://docs.nevolagroup.com/errors/access_denied" } } } } } }, "NotFound": { "description": "Resource not found.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "notFound": { "value": { "code": "resource_not_found", "message": "No profile exists with ID prof_01HXY7R4F2M8K6P0QJ9T3V5NWA.", "request_id": "req_01HXY9H7J43KX4KQH3DPSKJ2S3", "doc_url": "https://docs.nevolagroup.com/errors/resource_not_found" } } } } } }, "Conflict": { "description": "Request conflicts with the current resource state.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conflict": { "value": { "code": "idempotency_conflict", "message": "The idempotency key was reused with a different request body.", "request_id": "req_01HXY9JHDE2Q74SBR87WZ51S5F", "doc_url": "https://docs.nevolagroup.com/errors/idempotency_conflict" } } } } } }, "UnprocessableEntity": { "description": "Request syntax is valid, but one or more fields failed validation.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validationFailed": { "value": { "code": "validation_failed", "message": "content_type must be one of newsletter, audio_script, daily_drop, course_step, checkpoint.", "request_id": "req_01HXY9K90P3NBRWZ3V4N1G8C4C", "doc_url": "https://docs.nevolagroup.com/errors/validation_failed" } } } } } }, "RateLimited": { "description": "Too many requests.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" }, "example": 2 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rateLimited": { "value": { "code": "rate_limit_exceeded", "message": "Too many requests. Retry after the time in the Retry-After header.", "request_id": "req_01HXY9M00HT14P1K3FT0TTQYHX", "doc_url": "https://docs.nevolagroup.com/errors/rate_limit_exceeded" } } } } } }, "InternalServerError": { "description": "Internal server error.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal": { "value": { "code": "internal_error", "message": "An internal error occurred. Retry the request or contact support with the request_id.", "request_id": "req_01HXY9MTGZRZVPENB1F6HYFCR2", "doc_url": "https://docs.nevolagroup.com/errors/internal_error" } } } } } } } } }