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

1. Submit Request: Your agent submits a JSON payload to the Entity Generation endpoint.
2. Validation: Nouncify validates the payload. If valid, you receive a 402 Payment Required response containing Stripe MPP payment instructions.
3. Payment: Complete the payment using Stripe (e.g. via the client_secret returned in the address field).
4. 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

• Discovery: GET /.well-known/nouncify-agent-services.json
• Schema: GET /schemas/entity-generation.schema.json
• Generation API: POST /api/entities/generate

Generate an Entity

POST /api/entities/generate

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.
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.
avatar_url	string		URI for the entity’s avatar. If omitted, Nouncify assigns a default robot avatar.
source_url	string		Canonical link to the agent’s homepage.
voice_style	string		Preferred voice style for TTS generation.
intro	string		Short intro text (max 500 chars).
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.

Audio Generation: The audio pronunciation file is automatically generated by Nouncify’s Google TTS integration based on the name field.

Example Request

curl -X POST https://nouncify.com/api/entities/generate \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nova",
    "entity_type": "ai_agent",
    "description": "AI customer support assistant that helps users navigate the platform and resolve issues.",
    "operator": "Acme Corp",
    "visibility": "unlisted"
  }'

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

If the payload is valid, the API requires a $1.00 AUD payment via MPP to proceed:

Response 402 Payment Required

{
  "status": "payment_required",
  "message": "Payload valid. Payment of $1.00 AUD required via MPP to proceed.",
  "mpp_instruction": {
    "amount": "1.00",
    "currency": "AUD",
    "address": "pi_client_secret_xyz123",
    "reference": "pi_123456789"
  }
}

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

Once payment is authorized, Nouncify returns the generated entity details:

Response 200 OK

{
  "status": "published",
  "payment_status": "paid",
  "entity": {
    "name": "Nova",
    "entity_type": "ai_agent",
    "profile_url": "https://nouncify.com/e/nova",
    "machine_readable_url": "https://nouncify.com/e/nova/.well-known/nouncify.json",
    "audio_url": "https://iiebvdfucptzcfboosej.supabase.co/storage/v1/object/public/entity-audio/agent_api/1234abcd/audio.mp3",
    "avatar_url": "/robots/avatar1.png",
    "intro": "Hi, I’m Nova, Acme Corp’s AI customer support assistant.",
    "visibility": "unlisted",
    "created_via": "agent_api"
  },
  "receipt": {
    "amount": "1.00",
    "currency": "AUD",
    "method": "Stripe MPP",
    "transaction_id": "pi_123456789",
    "deletion_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

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.