> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neariq.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Content Studio
> Generate draft content — GBP posts, blogs, landing pages, FAQs, social posts, and review responses — for the active business.
`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.
Your API key from Settings > API Keys
Filter by content type: `landing_page`, `faq`, `gbp_post`, `social_post`, `review_response_template`, or `blog_outline`
Number of results to return (max 100)
```bash cURL theme={null}
curl "https://app.neariq.io/api/v1/content?type=gbp_post&limit=10" \
-H "X-NearIQ-Key: niq_your_key_here"
```
```javascript JavaScript theme={null}
const neariq = new NearIQ({ apiKey: 'niq_your_key_here' })
const { generations } = await neariq.content({ type: 'gbp_post' })
```
## 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
```json theme={null}
{
"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
```bash theme={null}
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. |
### Refinement example
```bash theme={null}
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
```json theme={null}
{
"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.
```bash theme={null}
curl "https://app.neariq.io/api/businesses/me/content/f2d4b5cc-1c25-4d87-9e8b-72a6579b9641" \
-b "session cookie"
```
```json theme={null}
{
"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.
```bash theme={null}
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`. |
```json theme={null}
{
"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.
```bash theme={null}
curl -X DELETE "https://app.neariq.io/api/businesses/me/content/f2d4b5cc-1c25-4d87-9e8b-72a6579b9641" \
-b "session cookie"
```
```json theme={null}
{
"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.
```bash theme={null}
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" }'
```
```json theme={null}
{
"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.
```bash theme={null}
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 }'
```
```json theme={null}
{
"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.
```bash theme={null}
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" }'
```
```json theme={null}
{
"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.
```bash theme={null}
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" }'
```
```json theme={null}
{
"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.
```bash theme={null}
curl "https://app.neariq.io/api/businesses/me/video?id=vid_123" \
-b "session cookie"
```
```json theme={null}
{
"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.
```bash theme={null}
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
}'
```
```json theme={null}
{
"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.
```bash theme={null}
curl "https://app.neariq.io/api/businesses/me/video/talking-avatar?id=tav_opaque" \
-b "session cookie"
```
```json theme={null}
{
"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.
```bash theme={null}
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 }'
```
```json theme={null}
{
"jobId": "job_123",
"status": "queued",
"jobToken": "job_token"
}
```
## GET /api/businesses/me/video/composite
Polls composite status by `jobId` and `jobToken`.
```bash theme={null}
curl "https://app.neariq.io/api/businesses/me/video/composite?jobId=job_123&jobToken=job_token" \
-b "session cookie"
```
```json theme={null}
{
"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.
```bash theme={null}
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" }'
```
```json theme={null}
{
"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.
```bash theme={null}
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,..." }'
```
```json theme={null}
{
"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. |
```bash theme={null}
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" }'
```
```json theme={null}
{
"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 |
## Related endpoints
* [Image Generation](/api-reference/endpoints/image-generation) — generate AI images with 15 style presets
* [Video Generation](/api-reference/endpoints/video-generation) — generate AI video clips with voiceover