REST APIUpdated for MCP and REST v1

REST API

The REST API mirrors the MCP capabilities under `/public/v1` for direct server-side integrations.

Base URL

Productiontext

https://api.novabrand.ai/public/v1

Every REST endpoint requires an api-scoped key in the Authorization header. Async operations return 202 Accepted; read operations and polling return 200 OK.

Response shape

Successful REST responses return a top-level data object. Failed requests return a top-level error object with type and message fields. Use the message for user-facing recovery and the type for programmatic branching. The object inside data matches the corresponding MCP tool result, so the field references in MCP Tools apply here too.

HTTP status	Meaning	Typical fix
200	Read or polling request succeeded.	Use the returned `data`.
202	Async project setup or generation was accepted.	Store the returned id and poll the status endpoint.
400	Validation failed.	Check required fields, enum values, and array inputs.
401	Missing or invalid key.	Send a valid `Authorization: Bearer nb_sk_...` header.
402	Not enough credits.	Check `/credits` or adjust the request.
403	The key cannot access that surface or account resource.	Confirm key scope and project ownership.
404	Requested project, image, model, or generation was not found.	List resources again and retry with returned IDs.

Error types

Branch on the HTTP status first. The error.type field gives a more specific reason for the same failure.

error.type	HTTP	Meaning
VALIDATION_ERROR	400	A required field, enum value, or array input was invalid.
PROJECT_LIMIT_EXCEEDED	400	The plan project limit was reached.
QUOTA_EXCEEDED	402	Not enough credits for the request.
FORBIDDEN	403	The key or account cannot access the resource.
NOT_FOUND	404	The project, image, model, or generation was not found.
internal_error	500	An unexpected server error. Retry after a short wait.

Endpoints

GET/projectsapi

List projects.

POST/projectsapi

Create a project and start brand setup.

GET/brand-analysis/:idapi

Check setup status.

GET/projects/:projectId/product-imagesapi

List product images.

GET/projects/:projectId/modelsapi

List reusable brand models.

POST/adsapi

Generate ad creatives asynchronously.

POST/model-shotsapi

Generate model shots asynchronously.

GET/generations/:id?kind=ad|model_shotapi

Check generation status.

GET/creditsapi

Get credit balance and limits.

Generate an ad

POST /adsbash

curl -X POST "https://api.novabrand.ai/public/v1/ads" \
  -H "Authorization: Bearer nb_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "project_uuid_here",
    "product_image_uuids": ["file_uuid_here"],
    "generation_type": "campaign",
    "variant_count": 4,
    "aspect_ratio": "4:5",
    "custom_prompt": "Premium skincare campaign on a marble bathroom counter."
  }'

Async responsejson

{
  "data": {
    "kind": "ad",
    "id": "asset_uuid_here",
    "job_id": "job_uuid_here",
    "credits_used": 4,
    "note": "Generation is running. Poll check_generation with kind=\"ad\" and this id until completed is true to get image URLs and ad copy."
  }
}

Poll a generation

GET /generations/:idbash

curl "https://api.novabrand.ai/public/v1/generations/asset_uuid_here?kind=ad" \
  -H "Authorization: Bearer nb_sk_your_key_here"

Completed generation responsejson

{
  "data": {
    "kind": "ad",
    "status": "completed",
    "progress": 100,
    "current_stage": "complete",
    "error_message": null,
    "completed": true,
    "asset": {
      "status": "completed",
      "generation_type": "campaign",
      "variant_count": 4,
      "thumbnail_url": "https://assets.novabrand.ai/ad/preview.png",
      "generated_assets": [
        {
          "asset_url": "https://assets.novabrand.ai/ad/variant-1.png",
          "preview_url": "https://assets.novabrand.ai/ad/variant-1-preview.png",
          "title": "Marble counter hero",
          "ad_copy": "Glow that lasts all day.",
          "is_watermarked": false
        }
      ]
    }
  }
}

Check credits

GET /creditsbash

curl "https://api.novabrand.ai/public/v1/credits" \
  -H "Authorization: Bearer nb_sk_your_key_here"

Credits responsejson

{
  "data": {
    "limit": 50,
    "used": 12,
    "remaining": 38,
    "plan": "Standard",
    "billingPeriodStart": "2026-06-01T00:00:00.000Z",
    "billingPeriodEnd": "2026-07-01T00:00:00.000Z"
  }
}