> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nomiq.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Nomiq Developer Platform: REST API Integration Guide

> Integrate Nomiq's AI brand generation engine into your backend via REST API. Built for engineers and agency developers on Agency or Pro plans.

The Nomiq Developer Platform gives backend engineers and agency developers programmatic access to the same AI generation engine that powers the Brand Studio — letting you embed white-label brand identity creation directly into your own applications, automate high-volume client onboarding pipelines, and build fully custom front-ends on top of Nomiq's semantic routing architecture.

## Who This Is For

The Developer Platform is designed for two primary audiences:

* **Backend Engineers** who need to integrate brand generation as a feature inside enterprise SaaS products or internal tooling.
* **Agency Developers** who want to automate repetitive client onboarding flows and generate brand identities at scale without manual UI interaction.

If you are a non-technical end user looking for the visual Brand Studio, see the [Brand Studio guide](/brand-studio/core-identity) instead.

## Prerequisites

Before making your first API request, confirm that you have the following in place:

* An active Nomiq account on the **Agency** or **Pro** billing tier. Free tier accounts do not have API access enabled.
* A valid API key generated from **Workspace Settings → API Keys** in the Nomiq Dashboard.
* **Node.js v18+** or **Python 3.9+** installed locally if you plan to use one of the official Nomiq SDKs. Direct HTTP clients like `curl`, `fetch`, or `axios` work without any runtime requirement.

## Developer Workflow

Integrating Nomiq into your application follows a consistent four-step lifecycle from local setup through production deployment.

<Steps>
  <Step title="Provision Environment">
    Generate a Test API key from **Workspace Settings → API Keys** and store it in your local `.env` file as `NOMIQ_API_KEY`. Test keys connect to the sandbox environment at `sandbox.nomiq.com` and produce watermarked assets that do not count toward your billing quota. This keeps your development loop free of unintended charges.
  </Step>

  <Step title="Initialize Project via API">
    Send a `POST` request to `/v1/projects` to create a new Project container. The response returns a `project_id` — a workspace-scoped identifier you must pass on all subsequent generation and retrieval requests for that brand. Query or create projects dynamically; never hardcode a `project_id` in your source code.
  </Step>

  <Step title="Execute Generation">
    Send your user's semantic brand prompt to the `/v1/brands/generate` endpoint, passing the `project_id` from the previous step. Brand generation is asynchronous: the engine processes SVG logo vectors, CSS color variables, and font pairings typically within 3–10 seconds depending on asset complexity. Register a webhook URL in your project settings so Nomiq can `POST` the completed payload directly to your server when generation finishes.
  </Step>

  <Step title="Move to Production">
    Once you have validated output quality in the sandbox, swap your Test API key (`sk_test_...`) for a Live API key (`sk_live_...`) in your production environment variables and update your base URL from `sandbox.nomiq.com/v1` to `api.nomiq.com/v1`. No code changes are required beyond these two configuration values.
  </Step>
</Steps>

## SDK Installation

You can call Nomiq's REST API using any HTTP client. The official SDKs add type safety, automatic retries with exponential backoff, and built-in webhook signature verification on top of the raw HTTP layer.

<CodeGroup>
  ```bash npm theme={null}
  npm install @nomiq/node
  ```

  ```bash pip theme={null}
  pip install nomiq-python
  ```
</CodeGroup>

After installing, initialize the client with your API key from the environment:

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Nomiq } from '@nomiq/node';

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

  ```python Python theme={null}
  import nomiq
  import os

  client = nomiq.Client(
      api_key=os.environ.get("NOMIQ_API_KEY")
  )
  ```
</CodeGroup>

## Professional Best Practices

Keep the following two principles in mind as you build your integration — they prevent the most common production issues developers encounter.

**Use webhooks instead of polling.** Brand generation typically takes 3–10 seconds depending on vector complexity. There is no status-polling endpoint — the only supported delivery mechanism is a webhook. Register a webhook endpoint in your project settings and let Nomiq push the completed payload to your server asynchronously. Attempting to work around this with high-frequency requests to other endpoints will exhaust your per-minute rate limit quota, triggering HTTP `429` errors.

**Never hardcode project IDs.** A `project_id` is scoped to a specific workspace and environment. Committing a hardcoded project ID to your codebase will break immediately when you rotate environments or onboard additional workspaces. Always call `GET /v1/projects` to look up or `POST /v1/projects` to create projects at runtime.

## Troubleshooting

<AccordionGroup>
  <Accordion title="I'm receiving a 401 Unauthorized error on every request.">
    This almost always means one of three things: the `Authorization` header is missing entirely, the `Bearer ` prefix is absent (note the trailing space), or you are sending a Test key (`sk_test_...`) to the production endpoint at `api.nomiq.com`. Verify that your environment variable is resolving to a non-empty string by logging it immediately before the request, and confirm the target base URL matches the key type.
  </Accordion>

  <Accordion title="My SDK client initializes but every call returns 403 Forbidden.">
    A `403` from the Nomiq API indicates an authorization issue at the billing level rather than an authentication failure. Your workspace may have exceeded its monthly metered quota or has an unpaid invoice. Log into the Nomiq Dashboard and check the **Billing** tab to resolve any payment issues.
  </Accordion>

  <Accordion title="Generation requests succeed but I never receive a webhook delivery.">
    First, confirm that your webhook URL is publicly reachable and returns an HTTP `200` response within five seconds of receiving a `POST`. Nomiq will retry failed webhook deliveries up to five times using exponential backoff. You can inspect the full delivery log, including request and response bodies, under **Workspace Settings → Webhooks → Delivery History**.
  </Accordion>

  <Accordion title="I'm getting rate limit errors (429) during load testing.">
    Generation endpoints are subject to stricter per-minute caps than standard read/write endpoints. If your test scenario fires many concurrent generation requests, you will hit the limit for your plan tier. Implement exponential backoff with jitter in your retry logic, and review the [Rate Limits guide](/api-reference/rate-limits) to confirm the thresholds for your plan.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/developer-platform/authentication">
    Learn how to generate API keys, pass them in requests, and follow secure credential management practices.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Explore base URL conventions, pagination, idempotency, and the full endpoint reference.
  </Card>
</CardGroup>