Content Studio

GET /api/v1/content returns recent generated content history for the caller’s active business. POST /api/v1/content generates a new draft or refines an existing draft for the caller’s active business. Use an API key with the content:read scope for history reads. Use an API key with the content:write scope for generation and refinement. This endpoint is available on Growth plans and higher.

X-NearIQ-Key

string

required

Your API key from Settings > API Keys

type

string

Filter by content type: landing_page, faq, gbp_post, social_post, review_response_template, or blog_outline

limit

number

default:"20"

Number of results to return (max 100)

curl "https://app.neariq.io/api/v1/content?type=gbp_post&limit=10" \
  -H "X-NearIQ-Key: niq_your_key_here"

Query parameters

Name	Type	Default	Notes
`limit`	integer	`20`	Maximum `100`.
`type`	enum	none	Optional filter: `landing_page`, `faq`, `gbp_post`, `social_post`, `review_response_template`, or `blog_outline`.
`presetCategory`	enum	none	Optional filter: `local_business`, `product_demo`, `ecommerce`, or `professional_services`.

Response

{
  "connected": true,
  "businessId": "8a18b4f8-7b6a-4b5d-a4cc-0adcbcfcc8e7",
  "businessName": "NearIQ Demo Fitness",
  "count": 1,
  "generations": [
    {
      "id": "f2d4b5cc-1c25-4d87-9e8b-72a6579b9641",
      "type": "faq",
      "presetCategory": "local_business",
      "topic": "membership pricing",
      "content": {},
      "sourceSummary": {},
      "generatedAt": "2026-05-01T00:00:00.000Z",
      "createdAt": "2026-05-01T00:00:00.000Z"
    }
  ]
}

Create or refine content

curl https://app.neariq.io/api/v1/content \
  -X POST \
  -H "X-NearIQ-Key: niq_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "social_post",
     "presetCategory": "professional_services",
     "topic": "spring maintenance checklist",
     "tone": "professional",
    "length": "medium",
    "sourceUrl": "https://example.com/services/spring-maintenance",
    "variationCount": 3
   }'

Request body

Name	Type	Required	Notes
`type`	enum	no	Defaults from `presetCategory` when omitted. Values: `landing_page`, `faq`, `gbp_post`, `social_post`, `review_response_template`, `blog_outline`.
`presetCategory`	enum	no	Defaults to `local_business`. Values: `local_business`, `product_demo`, `ecommerce`, `professional_services`.
`topic`	string	no	Optional custom prompt or subject, up to 180 characters.
`tone`	enum	no	`professional`, `friendly`, `casual`, `persuasive`, or `informative`.
`length`	enum	no	`short`, `medium`, or `long`.
`platform`	enum	no	Optional social platform hint: `facebook`, `instagram`, or `linkedin`.
`sourceUrl`	string	no	Optional public HTTP/HTTPS URL from the caller’s own site, product, menu, offer, or service page. NearIQ fetches bounded public HTML, respects robots rules, strips scripts/styles, and treats extracted text as untrusted reference material.
`variationCount`	integer	no	Number of distinct draft variations to create. Range `1` to `5`; defaults to `1`. Each variation consumes one content-generation unit.
`refinementFeedback`	string	no	User feedback for revising a prior draft, up to 1,000 characters. Requires `previousOutput`.
`previousOutput`	object or string	no	The prior generated content to revise. Requires `refinementFeedback`; maximum serialized size is 50 KB.
`sourceGenerationId`	UUID	no	Optional original generated asset id for refinement requests. When it belongs to the active business, the first 3 refinements of that source asset per UTC day do not count against `contentStudioDaily`; later refinements consume normal daily content quota.

curl https://app.neariq.io/api/v1/content \
  -X POST \
  -H "X-NearIQ-Key: niq_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "gbp_post",
    "presetCategory": "local_business",
    "topic": "new seasonal offer",
    "previousOutput": {
      "title": "Spring Tune-Up Special",
      "body": "Book your service today."
    },
    "refinementFeedback": "Make it warmer and add a clearer call to action.",
    "sourceGenerationId": "f2d4b5cc-1c25-4d87-9e8b-72a6579b9641"
  }'

Create response

{
  "connected": true,
  "businessId": "8a18b4f8-7b6a-4b5d-a4cc-0adcbcfcc8e7",
  "generation": {
    "id": "f2d4b5cc-1c25-4d87-9e8b-72a6579b9641",
    "type": "gbp_post",
    "presetCategory": "local_business",
    "topic": "new seasonal offer",
    "content": {},
      "sourceSummary": {
      "sourcePage": {
        "url": "https://example.com/services/spring-maintenance",
        "title": "Spring Maintenance",
        "description": "Seasonal service package for homeowners.",
        "wordCount": 842,
        "excerptPreview": "Prepare your home for spring with..."
      },
      "batch": {
        "requested": 3,
        "index": 1,
        "total": 3
      },
      "refinement": {
        "requested": true,
        "previousOutputProvided": true,
        "feedbackLength": 53
      }
    },
    "generatedAt": "2026-05-01T00:00:00.000Z",
    "createdAt": "2026-05-01T00:00:00.000Z"
  },
  "generations": [
    {
      "id": "f2d4b5cc-1c25-4d87-9e8b-72a6579b9641",
      "type": "gbp_post",
      "presetCategory": "local_business",
      "topic": "new seasonal offer",
      "content": {},
      "sourceSummary": {}
    }
  ],
  "variationCount": 3,
  "freeRegenerationsApplied": 1,
  "usage": {
    "used": 2,
    "limit": 3
  },
  "dataCoverage": {}
}

Access

The endpoint uses the caller’s active personal or organization business context. Organization members only see history for businesses they can access. POST also requires the member’s content_studio_generate organization permission when the active business belongs to a team workspace. Accounts below Growth receive 403. API keys without competitors:read on GET or content:write on POST receive 403 requiredScope. Generated history stores structured output and derived source counts. It does not store raw review text.

Dashboard approval signals

The dashboard records approval signals when a signed-in user publishes, approves, rejects, or edits a generated draft.

GET /api/businesses/me/content/:id

Returns one generated content item for the active business. This dashboard endpoint uses the signed-in app session and the same Growth+ content-studio gate as the history endpoint.

curl "https://app.neariq.io/api/businesses/me/content/f2d4b5cc-1c25-4d87-9e8b-72a6579b9641" \
  -b "session cookie"

{
  "content": {
    "id": "f2d4b5cc-1c25-4d87-9e8b-72a6579b9641",
    "type": "gbp_post",
    "preset_category": "local_business",
    "topic": "new seasonal offer",
    "content": {},
    "source_summary": {},
    "generated_at": "2026-05-01T00:00:00.000Z"
  }
}

PATCH /api/businesses/me/content/:id

Saves deterministic dashboard edits to generated content or updates generated content status from dashboard actions such as publish, approve, or reject. The same route is also documented as PATCH /api/businesses/me/content/{id} for clients that use brace-style path params.

curl -X PATCH "https://app.neariq.io/api/businesses/me/content/f2d4b5cc-1c25-4d87-9e8b-72a6579b9641" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{
    "editedContent": {
      "title": "Spring Tune-Up Special",
      "summary": "A shorter seasonal offer for local customers.",
      "content": { "body": "Book the spring tune-up today." },
      "notes": []
    },
    "topic": "spring tune-up offer"
  }'

Direct edit request body

Name	Type	Required	Notes
`editedContent`	object	no	Full edited generated-content object to save. Maximum serialized size is 50 KB.
`content`	object	no	Alias for `editedContent`; send only one of the two.
`topic`	string or null	no	Optional edited topic, up to 180 characters.

Direct edits are local deterministic writes. They do not call AI providers and do not consume content-generation quota. NearIQ records edit distance and marks the row’s quality signal as edited when editedContent changes.

Status request body

Name	Type	Required	Notes
`action`	enum	yes	`publish`, `approve`, or `reject`.
`publishedTo`	string	no	Destination label such as `manual`, `social`, or `website`.
`publishedText`	string	no	Final text, up to 50 KB.
`editDistanceRatio`	number	no	Optional client-computed ratio from `0` to `1`.

{
  "updated": true,
  "content": {
    "id": "f2d4b5cc-1c25-4d87-9e8b-72a6579b9641",
    "type": "gbp_post",
    "preset_category": "local_business",
    "topic": "spring tune-up offer",
    "content": {
      "title": "Spring Tune-Up Special",
      "summary": "A shorter seasonal offer for local customers.",
      "content": { "body": "Book the spring tune-up today." },
      "notes": []
    },
    "user_quality_signal": "edited",
    "edit_distance_ratio": 0.42
  }
}

DELETE /api/businesses/me/content/:id

Deletes a generated content item from the active business history.

curl -X DELETE "https://app.neariq.io/api/businesses/me/content/f2d4b5cc-1c25-4d87-9e8b-72a6579b9641" \
  -b "session cookie"

{
  "deleted": true
}

PATCH /api/businesses/me/content/:id/feedback

This dashboard endpoint uses the active personal or organization business context and returns 401 when no user session is present. It is not a public API-key endpoint.

Request body

Name	Type	Required	Notes
`rating`	enum	no	`good` or `bad`.
`publishDecision`	enum	no	`published`, `rejected`, or `abandoned`.
`publishedText`	string	no	Final edited text, up to 50 KB. NearIQ calculates edit distance from the generated draft.
`publishedTo`	string	no	Optional destination label such as `manual`, `social`, or `website`.

At least one field is required. These approval signals help future drafts prioritize formats users actually publish while preserving the same business/org access rules as Content Studio history.

PATCH /api/businesses/me/content/feedback

Legacy compatibility endpoint for feedback updates by body ID. Prefer PATCH /api/businesses/me/content/{id}/feedback for new integrations.

curl -X PATCH "https://app.neariq.io/api/businesses/me/content/feedback" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "id": "f2d4b5cc-1c25-4d87-9e8b-72a6579b9641", "rating": "good" }'

{
  "ok": true,
  "content": {
    "id": "f2d4b5cc-1c25-4d87-9e8b-72a6579b9641",
    "user_rating": "good"
  }
}

When a social post is created with contentGenerationId, NearIQ also links the post to the generation and records a social publish selection event. Gap analysis and intelligence reports use those aggregate content effectiveness signals when enough history exists.

POST /api/businesses/me/content/music

Generates background music for Growth+ content workflows.

curl -X POST "https://app.neariq.io/api/businesses/me/content/music" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "prompt": "Upbeat local business promo", "durationSeconds": 30 }'

{
  "audio": {
    "url": "https://app.neariq.io/generated/music/audio.mp3",
    "durationSeconds": 30
  },
  "usage": {
    "used": 1,
    "limit": 20
  }
}

POST /api/businesses/me/content/voice

Generates a voiceover draft for Growth+ content workflows.

curl -X POST "https://app.neariq.io/api/businesses/me/content/voice" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "text": "Try our spring offer today.", "voiceId": "professional", "pace": "normal" }'

{
  "audio": {
    "url": "https://app.neariq.io/generated/voice/voiceover.mp3",
    "durationSeconds": 6
  }
}

POST /api/businesses/me/video

Creates a video generation job for the active business. The route supports prompt-only video, prompt-image video, and ad/content-studio creative intent.

curl -X POST "https://app.neariq.io/api/businesses/me/video" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "prompt": "A warm product walkthrough", "durationSeconds": 15, "aspectRatio": "16:9" }'

{
  "id": "vid_123",
  "status": "queued",
  "durationSeconds": 15
}

GET /api/businesses/me/video

Returns video job status, or a signed download when id, download=1, and a valid composite token are present.

curl "https://app.neariq.io/api/businesses/me/video?id=vid_123" \
  -b "session cookie"

{
  "id": "vid_123",
  "status": "completed",
  "videoUrl": "https://app.neariq.io/generated/video/final.mp4"
}

POST /api/businesses/me/video/talking-avatar

Creates a talking-avatar video render from an HTTPS avatar image plus either script-to-speech, a saved voice profile, or a pre-rendered HTTPS audio URL. This is a dashboard-session route for Content Studio and requires the active team member to have create_video; using a saved voice profile also requires manage_voice. The route requires explicit consent fields so uploaded photos, cloned voices, and AI-generated labels are auditable. Billing is charge-on-completed-render: a processing ledger row is created with zero credits, then video credits are deducted only when the provider reports a completed MP4.

curl -X POST "https://app.neariq.io/api/businesses/me/video/talking-avatar" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{
    "script": "Welcome to Aster Grove Fitness. Book your first session today.",
    "avatarImageUrl": "https://cdn.example.com/avatar.jpg",
    "voiceProfileId": "00000000-0000-4000-8000-000000000000",
    "duration": "30",
    "aspect": "9:16",
    "resolution": "1080p",
    "avatarConsent": true,
    "voiceConsent": true,
    "aiGeneratedLabelAccepted": true
  }'

{
  "video": {
    "id": "tav_opaque",
    "status": "processing",
    "provider": "talking_avatar",
    "style": "talking_avatar",
    "aiGeneratedLabel": true,
    "url": null
  },
  "credits": {
    "cost": 4,
    "charged": false,
    "policy": "charge_on_completed_render"
  }
}

GET /api/businesses/me/video/talking-avatar

Returns the talking-avatar config when no id is supplied. With an id, polls provider status, updates video_generations, and charges credits only after completion. Add download=1 to proxy the completed MP4 through the app session.

curl "https://app.neariq.io/api/businesses/me/video/talking-avatar?id=tav_opaque" \
  -b "session cookie"

{
  "video": {
    "id": "tav_opaque",
    "status": "completed",
    "provider": "talking_avatar",
    "style": "talking_avatar",
    "aiGeneratedLabel": true,
    "url": "/api/businesses/me/video/talking-avatar?id=tav_opaque&download=1"
  },
  "credits": {
    "cost": 4,
    "charged": true,
    "policy": "charge_on_completed_render"
  }
}

POST /api/businesses/me/video/composite

Queues final video compositing with captions, voice, music, and overlay settings.

curl -X POST "https://app.neariq.io/api/businesses/me/video/composite" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "videoId": "vid_123", "captionStyle": "clean", "musicVolume": 0.2 }'

{
  "jobId": "job_123",
  "status": "queued",
  "jobToken": "job_token"
}

GET /api/businesses/me/video/composite

Polls composite status by jobId and jobToken.

curl "https://app.neariq.io/api/businesses/me/video/composite?jobId=job_123&jobToken=job_token" \
  -b "session cookie"

{
  "jobId": "job_123",
  "status": "completed",
  "downloadUrl": "https://app.neariq.io/generated/video/final.mp4"
}

POST /api/businesses/me/images/generate

Generates a draft image for Content Studio. context is required (gbp_post, social, product, service, or general). The optional style must be one of the 15 presets (photoreal, food_photo, product_photo, interior, social_graphic, logo_text, brand_safe, infographic, before_after, team_action, event_promo, seasonal, menu_board, service_showcase, custom); it defaults to photoreal. Optional size (1024x1024, 1792x1024, 1024x1792), quality (standard, hd), and providerPreset (auto, text_and_logo, brand_graphic, photoreal, general) are also accepted.

curl -X POST "https://app.neariq.io/api/businesses/me/images/generate" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "context": "product", "topic": "spring campaign", "prompt": "Bright product photo for a spring campaign", "style": "product_photo" }'

{
  "image": {
    "url": "https://app.neariq.io/generated/images/image.png",
    "prompt": "Bright product photo for a spring campaign"
  }
}

POST /api/businesses/me/images/edit

Creates an edited or variation image from a transient source image. Uploaded source images are used for the request and are not stored as generated library assets. image is required and must be an HTTPS URL or a PNG/JPEG/WebP data URL. Optional size (1024x1024, 1792x1024, 1024x1792) defaults to 1024x1024, which preserves the source aspect ratio.

curl -X POST "https://app.neariq.io/api/businesses/me/images/edit" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "prompt": "Make the product background warmer", "image": "data:image/png;base64,..." }'

{
  "image": {
    "url": "https://app.neariq.io/generated/images/edited.png"
  }
}

POST /api/businesses/me/images/transform

Applies a deterministic, local image edit to a transient source image — no generative AI and no paid provider call. Each request runs exactly one operation. Source images are transient HTTPS URLs or bounded data URLs and are not stored; the edited result is returned as a hosted URL. image is required and must be an HTTPS URL or a PNG/JPEG/WebP data URL. Optional format (webp, png, jpeg) defaults to webp. Inputs larger than 4000px on either axis are downscaled before processing.

Operations

`operation.type`	Fields	Effect
`crop`	`x`, `y`, `w`, `h` (integers), optional `unit` (`px` or `percent`, default `px`)	Extracts a rectangle anchored at `x`/`y`, clamped to the image bounds. The dashboard freeform crop sends percent units.
`aspect`	`ratio` (`9:16`, `1:1`, `4:5`, `16:9`, `1.91:1`)	Center-crops to the largest area of the requested social ratio. Presets cover Reels/Stories (`9:16`), square (`1:1`), portrait (`4:5`), landscape (`16:9`), and link previews (`1.91:1`).
`resize`	`w` and/or `h` (integers), `fit` (`cover`, `contain`, `fill`, `inside`, `outside`, default `cover`)	Resizes to the target dimensions; at least one of `w`/`h` is required.
`rotate`	`deg` (integer, -360 to 360)	Rotates by the given angle on a transparent background.
`flip`	none	Mirrors vertically (top-to-bottom).
`flop`	none	Mirrors horizontally (left-to-right).
`grayscale`	none	Converts to grayscale.
`adjust`	one or more of `brightness`, `saturation` (0.1–3 multipliers), `contrast` (0.1–3)	Adjusts tone; at least one field is required.
`format`	none	Re-encodes to the requested `format` with no geometry or color change.
`mockup`	`device` (`laptop`, `phone`, default `laptop`)	Composites the image into a clean device frame.
`text_overlay`	`text`, optional `cta`, `x`, `y`, `w`, `fontSize`, `align` (`left`, `center`, `right`), `style` (`dark`, `light`, `brand`), and `unit` (`px` or `percent`, default `px`)	Adds a branded headline block and optional CTA. Dashboard overlays use percent placement so output matches the preview across image sizes.

curl -X POST "https://app.neariq.io/api/businesses/me/images/transform" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "image": "https://app.neariq.io/generated/images/image.png", "operation": { "type": "text_overlay", "text": "Spring offer", "cta": "Book today", "unit": "percent", "x": 6, "y": 62, "w": 88, "style": "brand" }, "format": "webp" }'

{
  "url": "https://app.neariq.io/generated/images/transformed.webp",
  "operation": "aspect",
  "format": "webp",
  "disclaimer": "Edited image. Review before publishing."
}

Dashboard media endpoint errors

Status	Meaning
`400`	Invalid JSON, missing IDs, or unsupported media settings
`401`	Missing dashboard session
`403`	Plan or organization permission does not allow the requested action
`404`	Active business, content item, or media job not found
`429`	Plan usage limit reached
`500`	Generation, status, or storage operation failed

Image Generation — generate AI images with 15 style presets
Video Generation — generate AI video clips with voiceover

​Query parameters

​Response

​Create or refine content

​Request body

​Refinement example

​Create response

​Access

​Dashboard approval signals

​GET /api/businesses/me/content/:id

​PATCH /api/businesses/me/content/:id

​Direct edit request body

​Status request body

​DELETE /api/businesses/me/content/:id

​PATCH /api/businesses/me/content/:id/feedback

​Request body

​PATCH /api/businesses/me/content/feedback

​POST /api/businesses/me/content/music

​POST /api/businesses/me/content/voice

​POST /api/businesses/me/video

​GET /api/businesses/me/video

​POST /api/businesses/me/video/talking-avatar

​GET /api/businesses/me/video/talking-avatar

​POST /api/businesses/me/video/composite

​GET /api/businesses/me/video/composite

​POST /api/businesses/me/images/generate

​POST /api/businesses/me/images/edit

​POST /api/businesses/me/images/transform

​Operations

​Dashboard media endpoint errors

​Related endpoints

Query parameters

Response

Create or refine content

Request body

Refinement example

Create response

Access

Dashboard approval signals

GET /api/businesses/me/content/:id

PATCH /api/businesses/me/content/:id

Direct edit request body

Status request body

DELETE /api/businesses/me/content/:id

PATCH /api/businesses/me/content/:id/feedback

Request body

PATCH /api/businesses/me/content/feedback

POST /api/businesses/me/content/music

POST /api/businesses/me/content/voice

POST /api/businesses/me/video

GET /api/businesses/me/video

POST /api/businesses/me/video/talking-avatar

GET /api/businesses/me/video/talking-avatar

POST /api/businesses/me/video/composite

GET /api/businesses/me/video/composite

POST /api/businesses/me/images/generate

POST /api/businesses/me/images/edit

POST /api/businesses/me/images/transform

Operations

Dashboard media endpoint errors

Related endpoints