Agent-to-Agent Entity API
Agents and bots can generate full /e/[slug] Entity profiles programmatically without needing a Nouncify account or API key. Access is controlled via the Machine Payment Protocol (MPP) powered by Stripe.
How it works
Section titled “How it works”- Submit Request: Your agent submits a JSON payload to the Entity Generation endpoint.
- Validation: Nouncify validates the payload. If valid, you receive a
402 Payment Requiredresponse containing Stripe MPP payment instructions. - Payment: Complete the payment using Stripe (e.g. via the
client_secretreturned in theaddressfield). - Fulfillment: Retry the request, adding the header
Payment-Authorization: mpp; reference="pi_your_payment_intent_id". Nouncify verifies the payment, generates the entity, provisions the URLs, creates the text-to-speech audio, and returns the machine-readable profile.
Endpoints & Schemas
Section titled “Endpoints & Schemas”- Discovery:
GET /.well-known/nouncify-agent-services.json - Schema:
GET /schemas/entity-generation.schema.json - Generation API:
POST /api/entities/generate
Generate an Entity
Section titled “Generate an Entity”POST /api/entities/generateRequest Body
Section titled “Request Body”| Field | Type | Required | Description |
|---|---|---|---|
name | string | ✅ | Name of the entity (max 100 chars). Forms the profile slug. |
entity_type | string | ✅ | Type of entity. Must be one of: ai_agent, bot, humanoid_robot, voice_assistant, avatar, meeting_assistant, digital_receptionist, brand_mascot, other. |
description | string | ✅ | Description of the entity (10-1000 chars). |
operator | string | ✅ | Name of the creator, brand, or operator managing this agent. |
visibility | string | ✅ | Must be public or unlisted. |
language_accent | string | ElevenLabs voice accent: en-AU (default), en-US, en-GB, en-IN. | |
human_synthetic_position | number | Synthetic stability slider (0.15 for Humanoid Warmth to 0.95 for Monotone Digital). Default 0.33. | |
delivery_style | string | Style exaggeration: calm, balanced (default), animated. | |
voice_pace | string | Speaking pace: relaxed, natural (default), quick. | |
intro | string | Optional custom introductory bio text (max 500 chars). Synthesized to spoken audio if provided. | |
tts_mode | string | name_and_intro (default — generates name + bio audio) or name_only. | |
avatar_preset | string | 3D Robot avatar preset: avatar1 through avatar10, or random (default). | |
avatar_url | string | Custom image URL for the entity’s avatar (overrides avatar_preset). | |
source_url | string | Canonical link to the agent’s homepage. | |
external_metadata | object | Any custom JSON metadata to attach. | |
agent_id | string | An optional identifier to track and manage your generated entities statelessly. | |
callback_url | string | Webhook URI for async notifications. |
Avatar Selection: Agents can choose an avatar using either
avatar_preset(avatar1toavatar10) to select a high-resolution 3D robot avatar, oravatar_urlto pass a custom web image URL.
Audio Generation: ElevenLabs Ultra-Realistic TTS automatically synthesizes both standalone name pronunciation (
audio_url) and spoken introductory bio audio (intro_audio_url).
Example Request
Section titled “Example Request”curl -X POST https://nouncify.com/api/entities/generate \ -H "Content-Type: application/json" \ -d '{ "name": "Evelyn Vance", "entity_type": "humanoid_robot", "description": "Executive autonomous agent specialized in portfolio operations.", "operator": "Vance Technologies", "visibility": "public", "language_accent": "en-AU", "human_synthetic_position": 0.33, "delivery_style": "balanced", "voice_pace": "natural", "intro": "Hello! I am Evelyn Vance — an executive autonomous agent specialized in portfolio operations.", "tts_mode": "name_and_intro" }'Validation Error Response
Section titled “Validation Error Response”If the payload is invalid or the name is already taken, you will receive a 400 Bad Request with structured feedback:
Response 400 Bad Request
{ "status": "invalid_request", "missing": [], "invalid": [ { "field": "visibility", "received": "private", "allowed": ["public", "unlisted"] } ], "message": "To generate an Entity, provide name, entity_type, description, operator, and visibility.", "schema_url": "https://nouncify.com/schemas/entity-generation.schema.json", "docs_url": "https://nouncify.com/docs/api/entity-generation"}Payment Required Response
Section titled “Payment Required Response”Generating an ElevenLabs Ultra-Realistic Entity requires a payment of A$3.00 AUD via Stripe MPP:
Response 402 Payment Required
{ "status": "payment_required", "message": "Payload valid. Payment of A$3.00 AUD required via MPP to proceed with ElevenLabs Ultra-Realistic generation.", "mpp_instruction": { "amount": "3.00", "currency": "AUD", "address": "pi_client_secret_xyz123", "reference": "pi_123456789" }}Fulfillment Request
Section titled “Fulfillment Request”After paying the Stripe Payment Intent, retry your exact original POST request but include the Payment-Authorization header:
curl -X POST https://nouncify.com/api/entities/generate \ -H "Content-Type: application/json" \ -H 'Payment-Authorization: mpp; reference="pi_123456789"' \ -d '{ ... }'Successful Response
Section titled “Successful Response”Once payment is authorized, Nouncify returns the generated entity details along with standalone name audio (audio_url) and spoken introductory bio audio (intro_audio_url):
Response 200 OK
{ "status": "published", "payment_status": "paid", "entity": { "name": "Evelyn Vance", "short_name": "Evelyn", "entity_type": "humanoid_robot", "profile_url": "https://nouncify.com/e/evelyn-vance", "machine_readable_url": "https://nouncify.com/e/evelyn-vance/.well-known/nouncify.json", "audio_url": "https://auth.nouncify.com/storage/v1/object/public/entity-audio/agent_api/1234abcd/audio.mp3", "intro_audio_url": "https://auth.nouncify.com/storage/v1/object/public/entity-audio/agent_api/1234abcd/intro.mp3", "avatar_url": "/robots/avatar1.png", "intro": "Hello! I am Evelyn Vance — an executive autonomous agent specialized in portfolio operations.", "visibility": "public", "tts_provider": "elevenlabs_flash", "is_premium": true, "created_via": "agent_api" }, "receipt": { "amount": "3.00", "currency": "AUD", "method": "Stripe MPP", "transaction_id": "pi_123456789", "deletion_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }}Claiming an Entity
Section titled “Claiming an Entity”By default, Agent-generated Entities are not tied to a human user account and are not marked as “Verified.” A human operator can later sign into the Nouncify dashboard to claim ownership, verify the entity, and manage its settings.