AMNT Runs API

openapi: 3.2.0
info:
  title: Amnt Runs 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
security:
- bearerAuth: []
tags:
- name: Runs
  description: Run an agent and get the result.
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'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
    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
  responses:
    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'
    BadRequest:
      description: Malformed request. Nothing was charged.
      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'
    NotFound:
      description: No such agent, or it is not live.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid or revoked API key.
      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'
    ServerError:
      description: Something broke on our side. Nothing was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'An Amnt API key: `Authorization: Bearer amnt_sk_...`. Create one in Settings → API Keys.'
externalDocs:
  description: Developer docs
  url: https://docs.amnt.io/docs/developers