Quickstart · 5 min

Nevola Engine API quickstart

This guide creates one profile and generates one personalized content item. It takes about five minutes.

Base URL:

https://api.sandbox.nevolagroup.com/v1

Use sandbox keys while you build. Sandbox keys start with nev_test_. Live keys start with nev_live_.

1. Authenticate

Create an API key in the Nevola dashboard, then send it as a bearer token in the Authorization header.

export NEVOLA_API_KEY="nev_test_51K9x_example"

Every request must include the header:

Authorization: Bearer nev_test_51K9x_example

For POST requests, include an Idempotency-Key header when retrying from your application. Reuse the same key for the same logical operation. Use a new key for a new operation.

2. Your first profile

A profile is the context handle used by personalization requests. It is not a user account. Keep your own user model in your application and store the returned profile_id beside it.

curl https://api.sandbox.nevolagroup.com/v1/profiles \
  -X POST \
  -H "Authorization: Bearer $NEVOLA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_01HXY83CR0M3KD8X3K7E1QPK3H" \
  -d '{
    "external_user_id": "usr_9b1f0c8a72",
    "locale": "en-GB",
    "attributes": {
      "plan": "pro",
      "audience_segment": "editorial_manager",
      "lifecycle_stage": "activated",
      "content_preferences": {
        "format": "newsletter",
        "cadence": "weekday"
      }
    }
  }'

The response contains the profile ID:

{
  "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
}

Save prof_01HXY7R4F2M8K6P0QJ9T3V5NWA in your application.

3. Your first personalization

Call POST /personalize/content with the profile ID, a content type, a template ID, and a variant strategy.

curl https://api.sandbox.nevolagroup.com/v1/personalize/content \
  -X POST \
  -H "Authorization: Bearer $NEVOLA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_01HXY8A08CTTD2F3JZJQ4YJJ0N" \
  -d '{
    "profile_id": "prof_01HXY7R4F2M8K6P0QJ9T3V5NWA",
    "content_type": "newsletter",
    "template_id": "tmpl_newsletter_retention_v3",
    "variant_strategy": "stable"
  }'

Example response:

{
  "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
  }
}

4. Verify the response

Check these fields first:

  • content: the template-shaped payload to render or store in your product.
  • template_version: the registry version used for this generation.
  • signals: the temporal-contextual signal values referenced during generation.
  • usage: input and output units for metering.

Signals are deterministic for the profile, request time, locale, and active signal definition versions. If a generated item looks wrong, retrieve the profile and current signals before changing the template.

curl "https://api.sandbox.nevolagroup.com/v1/signals/temporal/prof_01HXY7R4F2M8K6P0QJ9T3V5NWA?at=2025-02-14T10:22:30Z" \
  -H "Authorization: Bearer $NEVOLA_API_KEY"

5. Next steps

  • Register webhooks for asynchronous sequence runs: POST /webhooks.
  • Start an ordered sequence: POST /personalize/sequence.
  • Poll sequence status: GET /personalize/sequence/{sequence_run_id}.
  • Read the OpenAPI spec: /docs/openapi.json.
  • Add SDK references for your stack: Node.js, Python, Ruby, or Go.