{
  "openapi": "3.1.0",
  "info": {
    "title": "Amnt API",
    "version": "1.0.0",
    "summary": "Run any agent on the Amnt marketplace with one HTTP call.",
    "description": "Every agent published on Amnt is callable over HTTP. One API key, one prepaid credit balance, one endpoint to run anything. A failed run is refunded automatically.",
    "termsOfService": "https://amnt.io/terms",
    "contact": {
      "name": "Amnt",
      "url": "https://amnt.io/contact"
    }
  },
  "servers": [
    {
      "url": "https://amnt.io",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer docs",
    "url": "https://docs.amnt.io/docs/developers"
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Runs",
      "description": "Run an agent and get the result."
    },
    {
      "name": "Agents",
      "description": "Discover agents and read their input contracts."
    },
    {
      "name": "Account",
      "description": "Your credit balance."
    },
    {
      "name": "SVG",
      "description": "AMNT 1.1 SVG: prompt or picture to a clean, editable SVG."
    }
  ],
  "paths": {
    "/api/v1/run": {
      "post": {
        "tags": [
          "Runs"
        ],
        "operationId": "runAgent",
        "summary": "Run an agent",
        "description": "Charges credits, runs the agent, pays the creator, returns the result. A failed run returns HTTP 200 with success:false and the credits already refunded - always check the success field, not the status code alone.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunRequest"
              },
              "examples": {
                "text": {
                  "summary": "A text agent",
                  "value": {
                    "agent": "alice/product-description",
                    "input": {
                      "prompt": "a walnut desk lamp"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Handled. Read `success` to know whether the agent worked.",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "description": "Not enough credits. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InsufficientCredits"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/agents": {
      "get": {
        "tags": [
          "Agents"
        ],
        "operationId": "listAgents",
        "summary": "List agents",
        "description": "Public metadata for every live agent. Free - listing never spends a credit.",
        "parameters": [
          {
            "name": "creator",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by creator handle."
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Free-text match on name and description."
          },
          {
            "name": "connector",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by connector id, e.g. llm."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of agents.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/agents/{handle}/{slug}": {
      "get": {
        "tags": [
          "Agents"
        ],
        "operationId": "getAgent",
        "summary": "Get one agent",
        "description": "The agent's published input contract - every field, its type, limits and default.",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/balance": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getBalance",
        "summary": "Check balance",
        "description": "Credits available to this key. The same balance the website shows.",
        "responses": {
          "200": {
            "description": "Your balance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Balance"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/svg/generate": {
      "post": {
        "tags": [
          "SVG"
        ],
        "operationId": "svgGenerate",
        "summary": "Prompt to SVG",
        "description": "Pass \"model\" to pick an AMNT model (amnt-auto picks the best per request). Without it: draws the picture for vector (flat colours, plain backdrop), then traces it into clean paths. $0.05, the same in any shape. Object layers +$0.02: each part is drawn whole underneath, so moving one leaves no hole. Takes 15-60 s. Any failure is refunded.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SvgGenerateRequest"
              },
              "examples": {
                "flat": {
                  "summary": "A flat mascot",
                  "value": {
                    "prompt": "a friendly fox mascot waving",
                    "style": "flat",
                    "formats": [
                      "pdf",
                      "png"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The SVG.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SvgResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "description": "Not enough Balance. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/svg/vectorize": {
      "post": {
        "tags": [
          "SVG"
        ],
        "operationId": "svgVectorize",
        "summary": "Picture to SVG",
        "description": "Traces a picture into clean paths at its own shape: soft edges snapped to real colours, no ring round cut-outs. $0.01. Object layers +$0.02.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SvgVectorizeRequest"
              },
              "examples": {
                "logo": {
                  "summary": "A logo",
                  "value": {
                    "image": "https://amnt.io/brand-kit/amnt-icon-512.png",
                    "background": "transparent"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The SVG.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SvgResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "description": "Not enough Balance. Nothing was charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "An Amnt API key: `Authorization: Bearer amnt_sk_...`. Create one in Settings → API Keys."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed request. Nothing was charged.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, invalid or revoked API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such agent, or it is not live.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unprocessable": {
        "description": "A value broke one of the agent's declared rules. Nothing was charged.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "More than 60 requests in one minute on this key.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds to wait."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServerError": {
        "description": "Something broke on our side. Nothing was charged.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unavailable": {
        "description": "The agent's owner could not be verified, so it refuses to run.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "RunRequest": {
        "type": "object",
        "required": [
          "agent",
          "input"
        ],
        "properties": {
          "agent": {
            "type": "string",
            "pattern": "^[^/]+/[^/]+$",
            "description": "The agent to run, as \"handle/slug\".",
            "examples": [
              "alice/product-description"
            ]
          },
          "input": {
            "type": "object",
            "additionalProperties": true,
            "description": "The agent's inputs, keyed by field name. Read the exact fields from GET /api/v1/agents/{handle}/{slug}. Undeclared keys are ignored."
          }
        }
      },
      "RunResponse": {
        "type": "object",
        "required": [
          "success"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "description": "False means the agent failed and you were refunded."
          },
          "output": {
            "description": "Shape depends on the connector: { kind: 'text', text } for text, { images: [url] } for pictures, { kind: 'json', data } for structured results."
          },
          "credits_used": {
            "type": "integer"
          },
          "credits_remaining": {
            "type": "integer"
          },
          "receipt": {
            "type": [
              "object",
              "null"
            ],
            "description": "Chain transaction details, for on-chain agents only."
          },
          "error": {
            "type": "string",
            "description": "Present when success is false. Written to be shown to a person."
          }
        }
      },
      "InsufficientCredits": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "credits_remaining": {
            "type": "integer"
          },
          "credits_required": {
            "type": "integer"
          }
        }
      },
      "AgentSummary": {
        "type": "object",
        "properties": {
          "agent": {
            "type": "string",
            "description": "The id to pass to /api/v1/run, as \"handle/slug\"."
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "connector": {
            "type": "string"
          },
          "connector_name": {
            "type": "string"
          },
          "price_credits": {
            "type": "integer",
            "description": "0 means free."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AgentList": {
        "type": "object",
        "properties": {
          "agents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentSummary"
            }
          },
          "total": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          }
        }
      },
      "InputField": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "The name to use inside the run request's input object."
          },
          "label": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "text",
              "longtext",
              "integer",
              "boolean",
              "enum",
              "image",
              "ratio"
            ]
          },
          "required": {
            "type": "boolean"
          },
          "default": {
            "description": "The creator's own value. Sending nothing uses it."
          },
          "options": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "max_length": {
            "type": [
              "integer",
              "null"
            ]
          },
          "min": {
            "type": [
              "integer",
              "null"
            ]
          },
          "max": {
            "type": [
              "integer",
              "null"
            ]
          },
          "placeholder": {
            "type": [
              "string",
              "null"
            ]
          },
          "help_text": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "AgentDetail": {
        "type": "object",
        "properties": {
          "agent": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "connector": {
            "type": "string"
          },
          "connector_name": {
            "type": "string"
          },
          "price_credits": {
            "type": "integer"
          },
          "input_fields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InputField"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Balance": {
        "type": "object",
        "properties": {
          "credits": {
            "type": "integer"
          },
          "credit_key": {
            "type": "string",
            "description": "The identity your credits sit on. Shared with the website."
          }
        }
      },
      "SvgOptions": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "default": "medium",
            "description": "low = bold and simple, medium = clean, high = closest to the picture."
          },
          "background": {
            "type": "string",
            "enum": [
              "transparent",
              "keep"
            ],
            "description": "Default transparent for generate, keep for vectorize."
          },
          "mode": {
            "type": "string",
            "enum": [
              "stacked",
              "cutout"
            ],
            "default": "stacked",
            "description": "cutout = no overlapping shapes (Figma, cutting machines)."
          },
          "colors": {
            "type": "integer",
            "minimum": 2,
            "maximum": 64
          },
          "palette": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^#[0-9a-fA-F]{6}$"
            },
            "description": "Snap every colour to these."
          },
          "layers": {
            "type": "string",
            "enum": [
              "color",
              "objects"
            ],
            "default": "color",
            "description": "objects = each thing as its own named, movable group."
          },
          "objects": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 4
          },
          "formats": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "svg",
                "png",
                "pdf",
                "eps",
                "dxf",
                "icons",
                "small",
                "webp",
                "jpg"
              ]
            }
          },
          "png_width": {
            "type": "integer",
            "minimum": 16,
            "maximum": 8192
          },
          "model": {
            "type": "string",
            "enum": [
              "amnt-auto",
              "amnt-svg-lite-1.1",
              "amnt-svg-1.1",
              "amnt-svg-pro-1.1",
              "amnt-trace-1.2",
              "amnt-vectorize-1.1"
            ],
            "description": "The AMNT model. Leave it out for AMNT Draw 1.2, the default. Old ids (amnt-svg-auto, amnt-svg-1 …) still work. amnt-auto AMNT Auto ($0.01-$0.25, picks per request) · amnt-svg-lite-1.1 AMNT SVG Lite 1.1 ($0.01: simple icons, charts, patterns) · amnt-svg-1.1 AMNT SVG 1.1 ($0.03: icons, logos, lettering) · amnt-svg-pro-1.1 AMNT SVG Pro 1.1 ($0.25: characters, detailed art) · amnt-trace-1.2 AMNT Trace 1.2 ($0.05: pixel art, scenes, illustrations) · amnt-vectorize-1.1 AMNT Vectorize 1.1 (vectorize only: $0.08 a logo or icon as clean code, else $0.01)."
          }
        }
      },
      "SvgGenerateRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SvgOptions"
          },
          {
            "type": "object",
            "required": [
              "prompt"
            ],
            "properties": {
              "prompt": {
                "type": "string",
                "minLength": 3,
                "maxLength": 2000
              },
              "style": {
                "type": "string",
                "enum": [
                  "auto",
                  "flat",
                  "icon",
                  "logo",
                  "illustration",
                  "pixel"
                ],
                "default": "auto"
              },
              "aspect": {
                "type": "string",
                "default": "1:1",
                "description": "\"auto\", a preset (1:1, 4:5, 3:4, 2:3, 9:16, 1:2, 5:4, 4:3, 3:2, 16:9, 2:1) or any W:H up to 3:1. Same price in every shape."
              }
            }
          }
        ]
      },
      "SvgVectorizeRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SvgOptions"
          },
          {
            "type": "object",
            "required": [
              "image"
            ],
            "properties": {
              "image": {
                "type": "string",
                "description": "https URL, data: URI or base64. 10 MB at most."
              }
            }
          }
        ]
      },
      "SvgResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "svg": {
            "type": "string"
          },
          "url": {
            "type": [
              "string",
              "null"
            ]
          },
          "files": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "paths": {
            "type": "integer"
          },
          "colors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "bytes": {
            "type": "integer"
          },
          "layers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "paths": {
                  "type": "integer"
                },
                "colors": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "score": {
            "type": [
              "object",
              "null"
            ],
            "description": "Quality score; null when there is nothing to compare against.",
            "properties": {
              "fidelity": {
                "type": "number"
              },
              "edge": {
                "type": "number"
              },
              "holes": {
                "type": "number"
              },
              "spill": {
                "type": "number"
              },
              "aspectOk": {
                "type": "boolean"
              }
            }
          },
          "model": {
            "type": "string",
            "description": "The AMNT SVG model asked for."
          },
          "ran": {
            "type": "string",
            "description": "The tier that made it (Auto picks one)."
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "price_usd": {
            "type": "number"
          },
          "balance_usd": {
            "type": "number"
          },
          "ms": {
            "type": "integer"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}