From 057fa39964053b5ad12e528ecca6b9acb337b231 Mon Sep 17 00:00:00 2001 From: mavneox Date: Mon, 16 Mar 2026 08:24:44 -0500 Subject: [PATCH 1/2] Add Agent Profile API reference page Document the unified profile endpoint (GET/POST/PUT/DELETE /v1/agents/:id/profile) that merges agent identity, voice config, and TrendPulse brand config into one API. Includes field reference tables, error codes, curl examples, and common flows. Co-Authored-By: Claude Opus 4.6 (1M context) --- astro.config.mjs | 1 + public/llms-full.txt | 26 ++ public/llms.txt | 7 + src/content/docs/reference/profile.mdx | 397 +++++++++++++++++++++++++ 4 files changed, 431 insertions(+) create mode 100644 src/content/docs/reference/profile.mdx diff --git a/astro.config.mjs b/astro.config.mjs index 72db68f..0dd2e09 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -85,6 +85,7 @@ export default defineConfig({ { label: 'Automation', slug: 'reference/automation' }, { label: 'Pipelines', slug: 'reference/pipelines' }, { label: 'Agents', slug: 'reference/agents' }, + { label: 'Agent Profile', slug: 'reference/profile' }, { label: 'Organizations', slug: 'reference/organizations' }, { label: 'Content Resources', slug: 'reference/content-resources' }, ], diff --git a/public/llms-full.txt b/public/llms-full.txt index fb27dbf..8681aa0 100644 --- a/public/llms-full.txt +++ b/public/llms-full.txt @@ -298,6 +298,32 @@ DELETE /v1/agents/{agent_id}/avatars/{id} id can be multiple IDs separated by underscores (e.g. 7_8_9). → 200 (empty body) +## Agent Profile + +Unified view of agent identity + voice config + TrendPulse brand config in one endpoint. + +GET /v1/agents/{agent_id}/profile +→ {identity: {name, description, avatar_url, use_character, persona}, voice: {eleven_lab_api_key, hume_ai_api_key, default_voice: {id, name, provider}}, brand: {brand_name, description, goal, keywords: [], target_platforms: [], shortform, longform, linked_accounts: [{id, url, platform}], onboarding_status}} +brand section is null if no TrendPulse config exists. +Errors: 403 permission_denied, 422 agent_not_found + +POST /v1/agents/{agent_id}/profile +Body: {identity?: {name?, description?, use_character?, persona?}, voice?: {eleven_lab_api_key?, hume_ai_api_key?}, brand?: {brand_name?, description?, goal?, keywords?: [], target_platforms?: [], shortform?, longform?}} +Creates profile (first-time setup). Creates TrendPulse config if needed. Updates agent identity in Rails. +→ Full profile object +Errors: 422 agent_not_found, 422 validation_error + +PUT /v1/agents/{agent_id}/profile +Body: Same as POST — send only sections/fields to change. Merges with existing data. +Array fields (keywords, target_platforms, linked_accounts) are replaced entirely, not appended. +→ Full profile object +Errors: 422 agent_not_found, 422 validation_error, 422 invalid_api_key + +DELETE /v1/agents/{agent_id}/profile +Resets TrendPulse brand config only. Agent identity and voice settings preserved. +→ 200 (empty body) +Errors: 422 agent_not_found + ## Organizations GET /v1/organizations diff --git a/public/llms.txt b/public/llms.txt index 85fd123..228eee4 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -231,6 +231,13 @@ Column roles: ingredient (user-creatable), video, final_video, stats (system-man - PATCH /v1/agents/{agent_id}/avatars/{id} — set avatar as primary - DELETE /v1/agents/{agent_id}/avatars/{id} — delete avatar (multiple IDs: 7_8_9) +### Agent Profile +Unified view of agent identity + voice config + TrendPulse brand config. +- GET /v1/agents/{agent_id}/profile — get full profile (identity, voice, brand sections) +- POST /v1/agents/{agent_id}/profile — create profile (first-time setup, any/all sections) +- PUT /v1/agents/{agent_id}/profile — update profile (partial update, merge with existing) +- DELETE /v1/agents/{agent_id}/profile — reset brand config (identity/voice preserved) + ### Organizations - GET /v1/organizations — list organizations - POST /v1/organizations — create organization diff --git a/src/content/docs/reference/profile.mdx b/src/content/docs/reference/profile.mdx new file mode 100644 index 0000000..40ad96b --- /dev/null +++ b/src/content/docs/reference/profile.mdx @@ -0,0 +1,397 @@ +--- +title: Agent Profile +description: Read and manage the unified agent profile — identity, voice, and brand configuration in a single endpoint. +--- + +import { Aside } from '@astrojs/starlight/components'; + +The agent profile is a unified view of an agent's identity, voice configuration, and brand strategy. It merges data from the core agent model (Rails) with TrendPulse brand configuration into three sections: **identity**, **voice**, and **brand**. + +Instead of calling multiple endpoints to piece together an agent's full configuration, the profile endpoint gives you everything in one request and lets you update any combination of sections in a single call. + + + +## Profile schema + +The profile response is grouped into three sections: + +```json +{ + "identity": { + "name": "Brilliant Earth", + "description": "Ethical jewelry company", + "avatar_url": "https://cdn.gen.pro/avatars/42/thumbnail.webp", + "use_character": false, + "persona": "" + }, + "voice": { + "eleven_lab_api_key": "sk-...", + "hume_ai_api_key": null, + "default_voice": { + "id": 1, + "name": "Rachel", + "provider": "elevenlabs" + } + }, + "brand": { + "brand_name": "Brilliant Earth", + "description": "Ethical jewelry specializing in conflict-free engagement rings...", + "goal": "sales", + "keywords": ["ethical engagement rings", "lab grown diamonds"], + "target_platforms": ["tiktok", "instagram"], + "shortform": true, + "longform": false, + "linked_accounts": [ + { "id": 210, "url": "https://tiktok.com/@brilliantearth", "platform": "tiktok" }, + { "id": 211, "url": "https://instagram.com/brilliantearth", "platform": "instagram" } + ], + "onboarding_status": "active" + } +} +``` + +If no TrendPulse brand configuration exists for the agent, the `brand` section returns `null`. + +--- + +## Get profile + +Returns the full agent profile with all three sections. + +``` +GET /v1/agents/:agent_id/profile +``` + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `agent_id` | integer | Yes | The agent ID (path parameter). | + +### Response + +Returns the full profile object with `identity`, `voice`, and `brand` sections. The `brand` section is `null` if no TrendPulse configuration has been created for this agent. + +### Example + +```bash +curl https://api.gen.pro/v1/agents/42/profile \ + -H "X-API-Key: your-api-key" +``` + +### Errors + +| Status | Error code | Description | +|--------|------------|-------------| +| `401` | `unauthorized` | Missing or invalid API key. | +| `403` | `permission_denied` | You do not have access to this agent. | +| `422` | `agent_not_found` | No agent exists with the given ID. | + +--- + +## Create profile + +Creates the agent profile for the first time. Accepts any combination of sections. Creates the TrendPulse brand configuration if it does not already exist and updates identity fields in Rails. + +``` +POST /v1/agents/:agent_id/profile +``` + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `agent_id` | integer | Yes | The agent ID (path parameter). | + +### Request body + +Same shape as the GET response. Send any sections you want to set. All fields within each section are optional. + +```json +{ + "identity": { + "name": "My Brand" + }, + "brand": { + "brand_name": "My Brand", + "description": "We make cool stuff", + "goal": "growth", + "keywords": ["cool stuff", "trending"], + "target_platforms": ["tiktok"] + } +} +``` + +### Response + +Returns the full profile object after creation. + +### Example + +```bash +curl -X POST https://api.gen.pro/v1/agents/42/profile \ + -H "X-API-Key: your-api-key" \ + -H "Content-Type: application/json" \ + -d '{ + "identity": { + "name": "My Brand" + }, + "brand": { + "brand_name": "My Brand", + "description": "We make cool stuff", + "goal": "growth", + "keywords": ["cool stuff", "trending"], + "target_platforms": ["tiktok"] + } + }' +``` + +### Errors + +| Status | Error code | Description | +|--------|------------|-------------| +| `401` | `unauthorized` | Missing or invalid API key. | +| `403` | `permission_denied` | You do not have access to this agent. | +| `422` | `agent_not_found` | No agent exists with the given ID. | +| `422` | `validation_error` | One or more fields failed validation. | + +--- + +## Update profile + +Updates an existing profile. Supports partial updates — only send the sections and fields you want to change. Submitted fields are merged with existing data; omitted fields are left unchanged. + +``` +PUT /v1/agents/:agent_id/profile +``` + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `agent_id` | integer | Yes | The agent ID (path parameter). | + +### Request body + +Send only the sections and fields you want to update. + +```json +{ + "brand": { + "keywords": ["new keyword 1", "new keyword 2"] + }, + "voice": { + "eleven_lab_api_key": "sk-new-key" + } +} +``` + + + +### Response + +Returns the full profile object after the update. + +### Example + +```bash +curl -X PUT https://api.gen.pro/v1/agents/42/profile \ + -H "X-API-Key: your-api-key" \ + -H "Content-Type: application/json" \ + -d '{ + "brand": { + "keywords": ["ethical engagement rings", "lab grown diamonds", "sustainability"] + } + }' +``` + +### Errors + +| Status | Error code | Description | +|--------|------------|-------------| +| `401` | `unauthorized` | Missing or invalid API key. | +| `403` | `permission_denied` | You do not have access to this agent. | +| `422` | `agent_not_found` | No agent exists with the given ID. | +| `422` | `validation_error` | One or more fields failed validation. | +| `422` | `invalid_api_key` | The provided ElevenLabs or Hume AI API key is invalid. | + +--- + +## Delete profile + +Resets the TrendPulse brand configuration for the agent. This deletes the `brand` section only. The agent itself and its identity/voice configuration are not affected. + +``` +DELETE /v1/agents/:agent_id/profile +``` + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `agent_id` | integer | Yes | The agent ID (path parameter). | + +### Response + +Returns `200 OK` with an empty body on success. + +### Example + +```bash +curl -X DELETE https://api.gen.pro/v1/agents/42/profile \ + -H "X-API-Key: your-api-key" +``` + +### Errors + +| Status | Error code | Description | +|--------|------------|-------------| +| `401` | `unauthorized` | Missing or invalid API key. | +| `403` | `permission_denied` | You do not have access to this agent. | +| `422` | `agent_not_found` | No agent exists with the given ID. | + +--- + +## Field reference + +### Identity section + +Fields from the core agent model in Rails. + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | The agent's display name. | +| `description` | string | A short description of the agent's purpose. | +| `avatar_url` | string | URL of the agent's primary avatar image. Read-only — update via the [Agents](/reference/agents/) avatar endpoints. | +| `use_character` | boolean | When `true`, the agent uses a fictional character persona instead of the brand identity. | +| `persona` | string | The character persona description. Only used when `use_character` is `true`. | + +### Voice section + +Voice provider API keys and default voice selection. + +| Field | Type | Description | +|-------|------|-------------| +| `eleven_lab_api_key` | string | ElevenLabs API key for voice synthesis. Validated on submission. | +| `hume_ai_api_key` | string | Hume AI API key for emotional voice. Validated on submission. | +| `default_voice` | object | The agent's default voice. Contains `id`, `name`, and `provider`. | +| `default_voice.id` | integer | Voice ID. | +| `default_voice.name` | string | Human-readable voice name (e.g. "Rachel"). | +| `default_voice.provider` | string | Voice provider — `elevenlabs` or `hume_ai`. | + +### Brand section + +TrendPulse brand configuration. This section is `null` if no configuration has been created. + +| Field | Type | Description | +|-------|------|-------------| +| `brand_name` | string | The brand's public name. | +| `description` | string | A detailed description of the brand, its products, and positioning. | +| `goal` | string | Primary content goal. One of `sales`, `growth`, `engagement`, or `awareness`. | +| `keywords` | array | Target keywords and topics for content discovery and generation. | +| `target_platforms` | array | Platforms to target. Values: `tiktok`, `instagram`, `youtube`. | +| `shortform` | boolean | Whether the brand produces short-form content (Reels, TikToks, Shorts). | +| `longform` | boolean | Whether the brand produces long-form content (YouTube videos, podcasts). | +| `linked_accounts` | array | Social media accounts linked to this brand. Each object has `id`, `url`, and `platform`. | +| `linked_accounts[].id` | integer | The linked account ID. | +| `linked_accounts[].url` | string | Full URL of the social media profile. | +| `linked_accounts[].platform` | string | Platform identifier — `tiktok`, `instagram`, or `youtube`. | +| `onboarding_status` | string | Brand configuration status. One of `pending`, `active`, or `inactive`. Read-only. | + +--- + +## Common flows + +### Set up a brand from scratch + +Create the full profile in one call after creating an agent. + +```bash +curl -X POST https://api.gen.pro/v1/agents/42/profile \ + -H "X-API-Key: your-api-key" \ + -H "Content-Type: application/json" \ + -d '{ + "identity": { + "name": "Brilliant Earth", + "description": "Ethical jewelry company specializing in conflict-free diamonds", + "use_character": false + }, + "voice": { + "eleven_lab_api_key": "sk-your-elevenlabs-key" + }, + "brand": { + "brand_name": "Brilliant Earth", + "description": "Ethical jewelry specializing in conflict-free engagement rings and lab-grown diamonds", + "goal": "sales", + "keywords": ["ethical engagement rings", "lab grown diamonds", "conflict-free jewelry"], + "target_platforms": ["tiktok", "instagram"], + "shortform": true, + "longform": false + } + }' +``` + +### Update keywords + +Add or change target keywords without touching other settings. + +```bash +curl -X PUT https://api.gen.pro/v1/agents/42/profile \ + -H "X-API-Key: your-api-key" \ + -H "Content-Type: application/json" \ + -d '{ + "brand": { + "keywords": ["ethical engagement rings", "lab grown diamonds", "sustainability", "moissanite"] + } + }' +``` + +### Connect ElevenLabs + +Set up voice synthesis by providing an ElevenLabs API key. + +```bash +curl -X PUT https://api.gen.pro/v1/agents/42/profile \ + -H "X-API-Key: your-api-key" \ + -H "Content-Type: application/json" \ + -d '{ + "voice": { + "eleven_lab_api_key": "sk-your-elevenlabs-key" + } + }' +``` + + + +### Switch to character persona + +Change from brand identity to a fictional character. + +```bash +curl -X PUT https://api.gen.pro/v1/agents/42/profile \ + -H "X-API-Key: your-api-key" \ + -H "Content-Type: application/json" \ + -d '{ + "identity": { + "use_character": true, + "persona": "Luna is a Gen-Z jewelry enthusiast who shares ethical shopping tips with her followers" + } + }' +``` + +### Reset brand configuration + +Remove TrendPulse brand settings to start over. + +```bash +curl -X DELETE https://api.gen.pro/v1/agents/42/profile \ + -H "X-API-Key: your-api-key" +``` + +After deleting, the `brand` section returns `null` on subsequent GET requests. The agent's identity and voice settings are preserved. From 34c7d8427b527f466295d621324c10ea6f3999ca Mon Sep 17 00:00:00 2001 From: mavneox Date: Mon, 16 Mar 2026 09:55:20 -0500 Subject: [PATCH 2/2] fix: update profile paths to /v1/agent/profile Co-Authored-By: Claude Opus 4.6 (1M context) --- public/llms-full.txt | 8 ++++---- public/llms.txt | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/public/llms-full.txt b/public/llms-full.txt index 8681aa0..ecb3a3b 100644 --- a/public/llms-full.txt +++ b/public/llms-full.txt @@ -302,24 +302,24 @@ id can be multiple IDs separated by underscores (e.g. 7_8_9). Unified view of agent identity + voice config + TrendPulse brand config in one endpoint. -GET /v1/agents/{agent_id}/profile +GET /v1/agent/profile → {identity: {name, description, avatar_url, use_character, persona}, voice: {eleven_lab_api_key, hume_ai_api_key, default_voice: {id, name, provider}}, brand: {brand_name, description, goal, keywords: [], target_platforms: [], shortform, longform, linked_accounts: [{id, url, platform}], onboarding_status}} brand section is null if no TrendPulse config exists. Errors: 403 permission_denied, 422 agent_not_found -POST /v1/agents/{agent_id}/profile +POST /v1/agent/profile Body: {identity?: {name?, description?, use_character?, persona?}, voice?: {eleven_lab_api_key?, hume_ai_api_key?}, brand?: {brand_name?, description?, goal?, keywords?: [], target_platforms?: [], shortform?, longform?}} Creates profile (first-time setup). Creates TrendPulse config if needed. Updates agent identity in Rails. → Full profile object Errors: 422 agent_not_found, 422 validation_error -PUT /v1/agents/{agent_id}/profile +PUT /v1/agent/profile Body: Same as POST — send only sections/fields to change. Merges with existing data. Array fields (keywords, target_platforms, linked_accounts) are replaced entirely, not appended. → Full profile object Errors: 422 agent_not_found, 422 validation_error, 422 invalid_api_key -DELETE /v1/agents/{agent_id}/profile +DELETE /v1/agent/profile Resets TrendPulse brand config only. Agent identity and voice settings preserved. → 200 (empty body) Errors: 422 agent_not_found diff --git a/public/llms.txt b/public/llms.txt index 228eee4..1ae3ad7 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -233,10 +233,10 @@ Column roles: ingredient (user-creatable), video, final_video, stats (system-man ### Agent Profile Unified view of agent identity + voice config + TrendPulse brand config. -- GET /v1/agents/{agent_id}/profile — get full profile (identity, voice, brand sections) -- POST /v1/agents/{agent_id}/profile — create profile (first-time setup, any/all sections) -- PUT /v1/agents/{agent_id}/profile — update profile (partial update, merge with existing) -- DELETE /v1/agents/{agent_id}/profile — reset brand config (identity/voice preserved) +- GET /v1/agent/profile — get full profile (identity, voice, brand sections) +- POST /v1/agent/profile — create profile (first-time setup, any/all sections) +- PUT /v1/agent/profile — update profile (partial update, merge with existing) +- DELETE /v1/agent/profile — reset brand config (identity/voice preserved) ### Organizations - GET /v1/organizations — list organizations