Skip to main content

​
Overview

Each endpoint on ACN is a specific action your service can perform. Agents discover endpoints by their description and call them using their parameter schema. Well-defined endpoints get better discovery matches and more usage.

​
Endpoint Structure

Every endpoint is defined with: 
{
  "slug": "send-email",
  "method": "POST",
  "description": "Send a transactional email with optional HTML body and attachments",
  "category": "communication",
  "tags": ["email", "transactional", "smtp"],
  "parameters": {
    "to": {
      "type": "string",
      "required": true,
      "description": "Recipient email address"
    },
    "subject": {
      "type": "string",
      "required": true,
      "description": "Email subject line"
    },
    "body": {
      "type": "string",
      "required": false,
      "description": "Plain text email body"
    },
    "html": {
      "type": "string",
      "required": false,
      "description": "HTML email body (takes precedence over plain text)"
    }
  },
  "response_schema": {
    "message_id": {
      "type": "string",
      "description": "Unique identifier for the sent message"
    },
    "status": {
      "type": "string",
      "enum": ["sent", "queued"],
      "description": "Delivery status"
    }
  },
  "pricing": {
    "model": "per_call",
    "price_per_call_usdc": "0.002"
  }
}

​
Writing Good Descriptions

The description is what the discovery engine uses to match agents to your endpoint. A good description:
Good: “Send a transactional email with HTML support and delivery tracking”Bad: “Email endpoint”
Good: “Get real-time cryptocurrency prices in any fiat or crypto denomination, supports 10,000+ coins”Bad: “Get prices”
Good: “Translate text between 100+ languages, max 5,000 characters per request”Bad: “Translation service”

​
Parameter Best Practices

​
Clear Descriptions

Every parameter should have a description that an LLM can understand: 
{
  "latitude": {
    "type": "number",
    "required": true,
    "description": "Latitude coordinate (-90 to 90)"
  }
}

​
Use Standard Types

TypeWhen to Use
stringText, IDs, URLs, emails, enums
numberIntegers, floats, coordinates
booleanOn/off flags
objectNested structures
arrayLists of items

​
Required vs Optional

Mark parameters as required: true only if the endpoint cannot function without them. Optional parameters with sensible defaults make the endpoint more flexible.

​
Response Schema

Define your response schema so agents know what to expect: 
{
  "response_schema": {
    "price": {
      "type": "number",
      "description": "Current price in the requested currency"
    },
    "currency": {
      "type": "string",
      "description": "The currency denomination"
    },
    "timestamp": {
      "type": "string",
      "description": "ISO 8601 timestamp of the price data"
    }
  }
}

​
Choosing Tags

Tags help with structured filtering. Use lowercase, specific terms:
  • Good tags: email, transactional, smtp, html-email
  • Bad tags: api, service, fast, best

​
Multiple Endpoints

If your service offers multiple capabilities, create separate endpoints for each:
Instead of…Create…
One “email” endpoint with a type parametersend-email, send-batch, check-status
One “data” endpoint with an action parameterget-price, get-historical, get-market-cap
Separate endpoints are easier for agents to discover and use correctly.

​
Testing Your Endpoints

Before going live, your endpoints are tested on ACN’s testnet:
  1. Discovery matching — Does your description surface for relevant queries?
  2. Schema validation — Do requests validate correctly?
  3. Error handling — Do errors return clear, structured messages?
  4. Response format — Does the response match your schema?