---
title: "Agent API"
method: POST
path: "/v1/agent"
tags: ["Suprsonic"]
---

# Agent API

`POST /v1/agent`

## Request

- Base URL: `https://suprsonic.ai`
- URL: `https://suprsonic.ai/v1/agent`
- Auth: HTTP bearer

O-mega Unified Agent API: single endpoint for all capabilities.

Instead of calling separate endpoints, agents call this one endpoint and either name the capability they need
with its params, or describe what they need in `request` and the system routes it. Either way it runs the
capability's own handler and answers its envelope.

## Request body

- AgentRequest
  - `capability` string, nullable: Which capability to run, with its params.
  - `params` object: The named capability's parameters.
  - `request` string, nullable: What you need, in plain words, instead of capability and params: it is routed to the capability that serves it, its params are filled from the words, and it runs.

## Response `200`

The call's envelope: success, data (the capability's result), metadata, and credits_used (0 when the call did not succeed).

- UnifiedResponse: Standard envelope for all unified API responses.
  - `success` boolean, required
  - `data` union
    - object
    - unknown[]
      - unknown
  - `error` UnifiedError: RFC 7807 problem detail for machine-actionable errors.
    - `type` string, required
    - `title` string, required
    - `status` integer, required
    - `detail` string, nullable
    - `is_retriable` boolean
    - `retry_after_seconds` integer, nullable
    - `alternative_action` string, nullable
    - `error_category` string
    - `caller_error` string, nullable
  - `metadata` UnifiedMetadata: Metadata included in every unified API response.
    - `provider_used` string, nullable
    - `providers_tried` string[]
    - `mode_used` string, nullable
    - `response_time_ms` integer
    - `request_id` string
    - `capability` string, nullable
    - `params` object, nullable
  - `credits_used` integer

## Other responses

- `401`: No API key, or one that was not found or is revoked.
- `402`: Not enough credits for this call. The error's alternative_action says where to add them.
- `403`: The account is restricted by a billing issue.
- `422`: Validation Error
- `429`: The key's rate limit is reached. The error's retry_after_seconds says when to try again.

---

[API](https://skmtc.dev/o-mega/apis/suprsonic-api.md) - [All operations](https://skmtc.dev/o-mega/apis/suprsonic-api/llms.txt) - [OpenAPI document](https://skmtc.dev/o-mega/apis/suprsonic-api/revisions/0eb535eb5679?raw)