> ## 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 REST API Reference: Base URL and Conventions

> Covers the Nomiq REST API base URL, Bearer authentication, cursor pagination, idempotency keys, and standard JSON response structure.

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
```

<Note>
  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.
</Note>

## 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`.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.nomiq.com/v1/projects \
    -H "Authorization: Bearer $NOMIQ_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```javascript Node.js theme={null}
  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();
  ```

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

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

  projects = client.projects.list()
  ```
</CodeGroup>

See the [Authentication guide](/developer-platform/authentication) 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:

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash curl theme={null}
  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"}'
  ```

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

  ```python Python theme={null}
  brand = client.brands.generate(
      project_id="proj_abc123",
      prompt="Minimalist fintech startup",
      idempotency_key="550e8400-e29b-41d4-a716-446655440000"
  )
  ```
</CodeGroup>

## Standard Response Structure

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Projects API" icon="folder" href="/api-reference/projects">
    Create and manage Project containers — the foundational resource that scopes all brand generation work.
  </Card>

  <Card title="Generation API" icon="wand-magic-sparkles" href="/api-reference/generation">
    Trigger asynchronous AI brand generation and retrieve completed SVG, color, and font assets.
  </Card>
</CardGroup>