Get one agent

GET /api/v1/agents/{handle}/{slug} — an agent's published input contract, field by field.

GET https://www.amnt.io/api/v1/agents/{handle}/{slug}

The contract for an agent's input. Read it once, generate a form or a tool definition from it, and stop guessing what to send.

curl https://www.amnt.io/api/v1/agents/alice/product-description \
  -H "Authorization: Bearer $AMNT_API_KEY"

Response

{
  "agent": "alice/product-description",
  "name": "Product description writer",
  "description": "Turns a product name into shop copy.",
  "connector": "llm",
  "connector_name": "Language model",
  "price_credits": 3,
  "input_fields": [
    {
      "key": "prompt",
      "label": "What is the product?",
      "type": "text",
      "required": true,
      "default": "a walnut desk lamp",
      "options": null,
      "max_length": 120,
      "min": null,
      "max": null,
      "placeholder": "a walnut desk lamp",
      "help_text": null
    },
    {
      "key": "tone",
      "label": "Tone",
      "type": "enum",
      "required": false,
      "default": "warm",
      "options": ["warm", "technical", "playful"],
      "max_length": null,
      "min": null,
      "max": null,
      "placeholder": null,
      "help_text": null
    }
  ],
  "created_at": "2026-07-02T10:14:22.114Z"
}

Reading `input_fields`

Field	Description
`key`	The name to use inside the `input` object when you run the agent
`label`	Human wording, written by the creator. Safe to show in a UI
`type`	`text`, `longtext`, `integer`, `boolean`, `enum`, `image` or `ratio`
`required`	A missing required field is a `400`
`default`	The creator's own value — the one that produced the samples on the agent page. Sending nothing uses it
`options`	The allowed values when `type` is `enum`. Anything else is a `422`
`max_length`	Character cap for text fields
`min` / `max`	Range for `integer` fields
`placeholder` / `help_text`	Extra wording for a form. Never required

`image` fields take a URL, not a file

A field of type image wants a public https:// URL. There is no upload endpoint on the API yet — host the file yourself, or upload it through the agent's page and reuse that URL.

Generating a payload from the contract

const meta = await fetch(
  `https://www.amnt.io/api/v1/agents/${handle}/${slug}`,
  { headers: { Authorization: `Bearer ${key}` } },
).then((r) => r.json());

// Start from the creator's own defaults, then override what you care about.
const input = Object.fromEntries(
  meta.input_fields
    .filter((f) => f.default !== null)
    .map((f) => [f.key, f.default]),
);

input.prompt = "a brushed steel kettle";

Status codes

Code	What it means
`200`	The agent exists and is live
`401`	Missing or invalid key
`404`	No such agent, or it is not live — an unpublished agent disappears from the API

The MCP server builds its tool schemas from these same fields, so an MCP client and your own code always see the same contract. See Tools and scopes.

Reading input_fields

Generating a payload from the contract

Status codes

On this page

Reading `input_fields`