Nomiq Node.js SDK — Complete Installation and Usage Guide

The @nomiq/node package is the official SDK for integrating Nomiq’s AI brand generation engine into Node.js applications. It wraps the Nomiq REST API with a fully typed interface, handles authentication, provides automatic retries, and includes built-in utilities for verifying webhook signatures — so you can focus on building rather than managing HTTP boilerplate.

Install the SDK

Add @nomiq/node to your project using your preferred package manager.

npm install @nomiq/node

yarn add @nomiq/node

pnpm add @nomiq/node

Store your API key in an environment variable (e.g., NOMIQ_API_KEY) and load it with a tool like dotenv. Never hardcode secrets directly in your source code or commit them to version control.

Initialize the Client

Import the Nomiq class and create a client instance by passing your API key. The client is the single entry point for every SDK method.

import { Nomiq } from '@nomiq/node';

const nomiq = new Nomiq({
  apiKey: process.env.NOMIQ_API_KEY as string,
});

const { Nomiq } = require('@nomiq/node');

const nomiq = new Nomiq({
  apiKey: process.env.NOMIQ_API_KEY,
});

The SDK authenticates every request using the apiKey you pass to the constructor, attaching it as a Bearer token to the Authorization header automatically. All requests are routed to https://api.nomiq.com/v1.

Create a Project

Before you can generate a brand, you need a Project. Projects are top-level containers that store all generated assets, strategy data, and history nodes associated with a client or campaign.

const project = await nomiq.projects.create({
  name: 'Acme Corp Rebrand',
  description: 'Enterprise software client — Q3 rebrand initiative.',
});

console.log(project.id); // "proj_1A2b3C4d5E"

A successful call returns a Project object. Save the project.id — you will need it to dispatch generation jobs.

{
  "id": "proj_1A2b3C4d5E",
  "object": "project",
  "name": "Acme Corp Rebrand",
  "description": "Enterprise software client — Q3 rebrand initiative.",
  "created_at": 1677649420,
  "metadata": {}
}

Generate a Brand

Call nomiq.brands.generate() with your project_id and a semantic prompt describing the brand. Because AI generation is computationally intensive, this endpoint returns a 202 Accepted immediately with a job object. The final assets are delivered via webhook when the job completes.

const job = await nomiq.brands.generate({
  project_id: 'proj_1A2b3C4d5E',
  prompt:
    'A modern coffee shop in Brooklyn specializing in cold brew. The logo should feature a minimalistic cold brew glass with a deep indigo and cream color palette. Typography should be a clean sans-serif.',
});

console.log(job.status); // "queued"
console.log(job.id);     // "job_9x8y7z6w"

The returned job object confirms the request was accepted:

{
  "object": "job",
  "id": "job_9x8y7z6w",
  "project_id": "proj_1A2b3C4d5E",
  "status": "queued",
  "created_at": 1677649420
}

Handle the Webhook

Configure a webhook endpoint in your Workspace Settings and listen for generation.success or generation.failed events. Nomiq signs every webhook request with an HMAC-SHA256 signature in the Nomiq-Signature header — always verify this before processing the payload.The example below shows a complete Express.js webhook handler. Note that express.raw() is required to access the raw request body for signature verification.

import express from 'express';
import crypto from 'crypto';

const app = express();
const webhookSecret = process.env.NOMIQ_WEBHOOK_SECRET as string;

app.post(
  '/webhook/nomiq',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const incomingSig = req.headers['nomiq-signature'] as string;
    const rawBody = req.body as Buffer;

    // Compute the expected HMAC-SHA256 signature
    const expectedSig = crypto
      .createHmac('sha256', webhookSecret)
      .update(rawBody)
      .digest('hex');

    if (
      !crypto.timingSafeEqual(
        Buffer.from(incomingSig, 'hex'),
        Buffer.from(expectedSig, 'hex')
      )
    ) {
      console.error('Webhook signature mismatch — request rejected.');
      return res.status(400).send('Invalid signature.');
    }

    const event = JSON.parse(rawBody.toString());

    if (event.type === 'generation.success') {
      const { job_id, project_id, assets } = event.data;
      console.log(`Job ${job_id} complete for project ${project_id}`);
      console.log('Logo SVG:', assets.logo_svg);
      console.log('Primary color:', assets.primary_color);
      console.log('Font family:', assets.font_family);

      // Queue further processing asynchronously; do not block this handler.
    } else if (event.type === 'generation.failed') {
      console.error(`Job ${event.data.job_id} failed:`, event.data.error.message);
    }

    // Return 200 immediately to acknowledge receipt.
    return res.status(200).send();
  }
);

app.listen(3000, () => console.log('Webhook listener running on port 3000'));

Projects

The nomiq.projects namespace exposes the full Projects API. Use these methods to manage your project containers programmatically.

Create a Project

const project = await nomiq.projects.create({
  name: 'Velocity Fitness App',
  description: 'Brand identity for a B2C fitness tracking startup.',
});

Retrieve a Project

Fetch the details of any existing project by its ID.

const project = await nomiq.projects.retrieve('proj_1A2b3C4d5E');

console.log(project.name);       // "Velocity Fitness App"
console.log(project.created_at); // 1677649420

List Projects

Returns all projects in your workspace, sorted newest-first. The response supports cursor-based pagination via limit and starting_after.

const { data: projects } = await nomiq.projects.list({
  limit: 20,
});

for (const project of projects) {
  console.log(`${project.id}: ${project.name}`);
}

// Paginate to the next page using the last item's ID as the cursor.
const { data: nextPage } = await nomiq.projects.list({
  limit: 20,
  starting_after: projects[projects.length - 1].id,
});

Delete a Project

await nomiq.projects.delete('proj_1A2b3C4d5E');

Deleting a project is permanent and irreversible. All associated generated assets, history nodes, and memory data are immediately removed from the database.

Brand Generation

Dispatch a brand generation job by providing a project_id and a descriptive prompt. You can optionally override the webhook delivery URL on a per-request basis.

const job = await nomiq.brands.generate({
  project_id: 'proj_1A2b3C4d5E',
  prompt:
    'A boutique law firm in Chicago focused on intellectual property. Professional and authoritative tone. Navy blue and gold color palette with a classic serif typeface.',
  webhook_url: 'https://your-app.com/webhooks/nomiq', // optional override
});

console.log(job.id);     // "job_9x8y7z6w"
console.log(job.status); // "queued"

Generation jobs typically complete within 3–10 seconds. Do not poll the API for status — listen for the generation.success webhook event instead.

Handling Webhooks

Nomiq delivers the completed brand assets to your webhook endpoint via a POST request. The full webhook payload for a generation.success event contains the SVG markup, primary color hex value, and font family recommendation:

{
  "event_id": "evt_5k6l7m8n",
  "type": "generation.success",
  "created_at": 1677649428,
  "data": {
    "job_id": "job_9x8y7z6w",
    "project_id": "proj_1A2b3C4d5E",
    "memory_id": "mem_X1y2Z3w4",
    "assets": {
      "logo_svg": "<svg>...</svg>",
      "primary_color": "#4f46e5",
      "font_family": "Inter"
    }
  }
}

The memory_id field in the payload identifies the Memory Node created for this generation. Persist it alongside your job record — you can pass it back to nomiq.brands.generate() as the memory_id parameter to refine this brand in a future iteration rather than starting from scratch. Always return a 200 OK response within 5 seconds of receiving a webhook. Offload any heavy processing (database writes, image transforms, notifications) to an asynchronous queue such as BullMQ or a background worker. If Nomiq does not receive a 200 within the timeout window, it retries using an exponential backoff strategy.

TypeScript Support

The @nomiq/node SDK is written in TypeScript and ships with complete type definitions — no @types/ package required. Every method parameter, response shape, and error object is fully typed, giving you autocomplete and compile-time safety out of the box.

import { Nomiq, NomiqProject, NomiqJob } from '@nomiq/node';

const nomiq = new Nomiq({ apiKey: process.env.NOMIQ_API_KEY as string });

async function createAndGenerate(
  clientName: string,
  brandPrompt: string
): Promise<NomiqJob> {
  const project: NomiqProject = await nomiq.projects.create({
    name: clientName,
  });

  const job: NomiqJob = await nomiq.brands.generate({
    project_id: project.id,
    prompt: brandPrompt,
  });

  return job;
}

Error Handling

The SDK throws structured error objects when the API returns a non-2xx response. Wrap your calls in try/catch and inspect the error.code property to branch your error handling logic.

import { Nomiq, NomiqAPIError } from '@nomiq/node';

const nomiq = new Nomiq({ apiKey: process.env.NOMIQ_API_KEY as string });

async function safeGenerate(projectId: string, prompt: string) {
  try {
    const job = await nomiq.brands.generate({
      project_id: projectId,
      prompt,
    });
    return job;
  } catch (error) {
    if (error instanceof NomiqAPIError) {
      switch (error.code) {
        case 'authentication_error':
          console.error('Invalid API key. Check your NOMIQ_API_KEY env var.');
          break;
        case 'rate_limit_exceeded':
          console.error('Rate limit hit. Back off and retry after a delay.');
          break;
        case 'invalid_project':
          console.error('Project not found:', projectId);
          break;
        default:
          console.error(`Nomiq API error [${error.code}]:`, error.message);
      }
    } else {
      // Network or unexpected error
      throw error;
    }
  }
}

Python SDK

Use the official Nomiq Python SDK to integrate brand generation into automation pipelines and backend services.

API Reference

Explore the full REST API reference, including all endpoints, request parameters, and response schemas.

​Projects

​Create a Project

​Retrieve a Project

​List Projects

​Delete a Project

​Brand Generation

​Handling Webhooks

​TypeScript Support

​Error Handling

Python SDK

API Reference

Projects

Create a Project

Retrieve a Project

List Projects

Delete a Project

Brand Generation

Handling Webhooks

TypeScript Support

Error Handling