Nomiq REST API Reference: Base URL and Conventions

The Nomiq REST API is organized around standard HTTP conventions: resource-oriented URLs, predictable HTTP verbs, JSON request and response bodies, and conventional status codes. If you have worked with Stripe, Twilio, or any other REST API, the patterns here will feel immediately familiar. This page describes the foundational rules that apply to every endpoint in the reference — read it once before diving into individual endpoint pages.

Base URL

Every API request must target the versioned base URL over HTTPS. Plain HTTP connections are rejected. All endpoints documented in this reference are relative to this base.

https://api.nomiq.com/v1

If you are using a Test API key during development, substitute the sandbox base URL:

https://sandbox.nomiq.com/v1

The Nomiq V1 API has a backward compatibility guarantee. New fields may be added to response objects, and new optional request parameters may be introduced, but existing field names, types, and endpoint paths will not change or be removed within the V1 namespace. Breaking changes will only ever appear under a new /v2 prefix, with a minimum six-month migration window announced in advance.

REST Conventions

The Nomiq API follows resource-oriented URL design. The primary conventions are:

GET — Retrieve a resource or a paginated list of resources. GET requests never modify state.
POST — Create a new resource or trigger an action (such as brand generation).
PATCH — Partially update an existing resource. Only the fields you include in the request body are modified.
DELETE — Permanently delete a resource. Deleted resources cannot be recovered.

Request bodies for POST and PATCH requests must be JSON-encoded with a Content-Type: application/json header. All response bodies are JSON-encoded regardless of the HTTP method.

Authentication

Every request to the Nomiq API requires a valid API key passed as a Bearer token in the Authorization header. Requests without a valid key return 401 Unauthorized.

curl https://api.nomiq.com/v1/projects \
  -H "Authorization: Bearer $NOMIQ_API_KEY" \
  -H "Content-Type: application/json"

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

// Pass the key once at initialization; the SDK attaches it to every request.
const nomiq = new Nomiq({
  apiKey: process.env.NOMIQ_API_KEY,
});

const projects = await nomiq.projects.list();

import nomiq
import os

client = nomiq.Client(
    api_key=os.environ.get("NOMIQ_API_KEY")
)

projects = client.projects.list()

See the Authentication guide for full details on key types, secure storage, and key rotation.

Pagination

All list endpoints (for example, GET /v1/projects and GET /v1/brands) use cursor-based pagination. This approach is more reliable than offset-based pagination for large, frequently updated datasets because it maintains a stable position in the list even when items are added or removed between requests.

Parameter	Type	Description
`limit`	integer	Number of records to return per page. Minimum `1`, maximum `100`, default `10`.
`starting_after`	string	A resource ID cursor. When provided, the API returns the page of results immediately after the object with this ID. Use the `next_cursor` value from the previous response.

A paginated response always includes the following envelope:

{
  "object": "list",
  "data": [
    {
      "id": "proj_abc123",
      "name": "Acme Corp Brand",
      "created_at": 1716000000
    },
    {
      "id": "proj_def456",
      "name": "Horizon Studio Identity",
      "created_at": 1715990000
    }
  ],
  "has_more": true,
  "next_cursor": "proj_def456"
}

When has_more is false, you have retrieved the final page. To fetch the next page, pass the value of next_cursor as the starting_after parameter in your next request.

Idempotency

For POST requests that create or mutate resources, you can attach an Idempotency-Key header containing a unique string (we recommend a UUID v4). If a request fails due to a network timeout or a transient server error, you can safely replay it with the same Idempotency-Key — Nomiq will return the result of the original request rather than executing the operation a second time. Idempotency keys are valid for 24 hours. After that window, reusing a key is treated as a new request.

curl -X POST "https://api.nomiq.com/v1/brands/generate" \
  -H "Authorization: Bearer $NOMIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"project_id": "proj_abc123", "prompt": "Minimalist fintech startup"}'

const brand = await nomiq.brands.generate(
  {
    project_id: 'proj_abc123',
    prompt: 'Minimalist fintech startup',
  },
  {
    idempotencyKey: '550e8400-e29b-41d4-a716-446655440000',
  }
);

brand = client.brands.generate(
    project_id="proj_abc123",
    prompt="Minimalist fintech startup",
    idempotency_key="550e8400-e29b-41d4-a716-446655440000"
)

Standard Response Structure

Successful single-resource responses return the resource object directly at the top level:

{
  "id": "proj_abc123",
  "object": "project",
  "name": "Acme Corp Brand",
  "status": "active",
  "created_at": 1716000000,
  "workspace_id": "ws_xyz789"
}

Error responses follow a consistent envelope regardless of the HTTP status code:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Required parameter 'project_id' is missing.",
    "code": "missing_required_param"
  }
}

The type field categorizes the error broadly (invalid_request_error, authentication_error, rate_limit_error, api_error), code gives you a machine-readable identifier for programmatic handling, and message provides a human-readable explanation suitable for internal logging.

Next Steps

Projects API

Create and manage Project containers — the foundational resource that scopes all brand generation work.

Generation API

Trigger asynchronous AI brand generation and retrieve completed SVG, color, and font assets.

​Base URL

​REST Conventions

​Authentication

​Pagination

​Idempotency

​Standard Response Structure

​Next Steps

Projects API

Generation API

Base URL

REST Conventions

Authentication

Pagination

Idempotency

Standard Response Structure

Next Steps