Справочник API (API-ключ)

Технические спецификации для конечных точек API Minara Agent.

API для разработчиков

Основная конечная точка для взаимодействия с диалоговым ИИ Minara.

Developer Chat

post

Developer chat endpoint supporting streaming, non-streaming, and asynchronous (background) response modes, with optional requestId-based idempotency.

Authorizations

BearerAuth

AuthorizationstringRequired

Format: Authorization: Bearer <YOUR_API_KEY>

Body

application/json

modestring · enumRequired

Required. Model mode: 'fast' for quick responses, 'expert' for in-depth analysis.

Possible values:

streambooleanOptional

Optional. Set to true for streaming (SSE), false (default) for standard JSON response. Cannot be combined with background.

Default: false

backgroundbooleanOptional

Optional. Set to true to run a non-streaming request asynchronously and poll the result later. Requires stream: false.

Default: false

requestIdstring · min: 1 · max: 128Optional

Optional. Client-generated idempotency key, unique within the API key. 1-128 chars matching ^[A-Za-z0-9._:-]+$.

Pattern: ^[A-Za-z0-9._:-]+$

chatIdstringOptional

Optional. Existing chat to continue. A new chat is created if omitted.

Responses

200

Successful response (stream/background not set, or a completed idempotent replay).

application/jsontext/event-stream

idstringOptional

Server-assigned request id. Present when a requestId was supplied.

requestIdstringOptional

Your idempotency key, echoed when one was provided.

chatIdstringOptional

Unique conversation ID.

messageIdstringOptional

Unique message ID for this response.

contentstringOptional

The AI-generated response content.

usageobjectOptional

Usage statistics for the request.

202

Accepted. Returned for background requests, or when an idempotent request is still running.

application/json

400

Bad Request. E.g. combining background=true with stream=true.

401

Unauthorized - Invalid or missing API key

409

Conflict. The requestId was already used with a different request, or has expired and cannot be reused.

post/v1/developer/chat

HTTPcURLJavaScriptPython

POST /v1/developer/chat HTTP/1.1
Host: api-developer.minara.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 127

{
  "mode": "fast",
  "stream": false,
  "background": false,
  "requestId": "text",
  "chatId": "text",
  "message": {
    "role": "user",
    "content": "text"
  }
}

{
  "id": "text",
  "requestId": "text",
  "chatId": "text",
  "messageId": "text",
  "content": "text",
  "usage": {}
}

Get Chat Request Status

get

Retrieve the status and result of any requestId-backed request (sync, stream, or background) by either the server-assigned id or your requestId. Records are retained for 24 hours after reaching a terminal state.

Authorizations

BearerAuth

AuthorizationstringRequired

Format: Authorization: Bearer <YOUR_API_KEY>

Path parameters

idstringRequired

The server-assigned id (e.g. bg_abc123) or your requestId. Must use the same API key that created the job.

Responses

200

Request status and result (if completed).

application/json

idstringOptional

Server-assigned request id.

requestIdstringOptional

Your idempotency key, if one was provided.

chatIdstringOptional

Chat the request belongs to.

statusstring · enumOptional

Current lifecycle status of the request.

Possible values:

executionModestring · enumOptional

How the request is being executed.

Possible values:

createdAtstring · date-timeOptional

startedAtstring · date-timeOptional

completedAtstring · date-timeOptional

expiresAtstring · date-timeOptional

When the record is removed (24h after reaching a terminal state).

401

Unauthorized - Invalid or missing API key

404

Not Found. The request does not exist or has expired.

get/v1/developer/chat/requests/{id}

HTTPcURLJavaScriptPython

GET /v1/developer/chat/requests/{id} HTTP/1.1
Host: api-developer.minara.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "requestId": "text",
  "chatId": "text",
  "status": "queued",
  "executionMode": "sync",
  "createdAt": "2026-07-16T14:18:40.289Z",
  "startedAt": "2026-07-16T14:18:40.289Z",
  "completedAt": "2026-07-16T14:18:40.289Z",
  "expiresAt": "2026-07-16T14:18:40.289Z",
  "result": {
    "id": "text",
    "requestId": "text",
    "chatId": "text",
    "messageId": "text",
    "content": "text",
    "usage": {}
  },
  "error": {
    "code": "processing_error",
    "message": "text"
  }
}

Intent to Swap Transaction

post

Convert natural language trading intent into an executable swap transaction payload. Compatible with OKX DEX by default.

Authorizations

BearerAuth

AuthorizationstringRequired

Format: Authorization: Bearer <YOUR_API_KEY>

Body

application/json

intentstringRequired

Required. Natural language swap intent (e.g., 'swap 0.1 ETH to USDC').

walletAddressstringRequired

Required. User wallet address (0x...).

chainstringOptional

Optional. Chain name (e.g., 'base', 'ethereum', 'bsc', 'arbitrum', 'optimism').

Responses

200

Swap transaction generated

application/json

401

Unauthorized - Invalid or missing API key

post/v1/developer/intent-to-swap-tx

HTTPcURLJavaScriptPython

POST /v1/developer/intent-to-swap-tx HTTP/1.1
Host: api-developer.minara.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 109

{
  "intent": "swap 0.1 ETH to USDC",
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
  "chain": "base"
}

{
  "intent": {
    "chain": "base",
    "inputTokenAddress": null,
    "inputTokenSymbol": "ETH",
    "outputTokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "outputTokenSymbol": "USDC",
    "amount": "100000000000000000",
    "userWalletAddress": "0x42a345F3d379B5060f0C36580bAF22C395B1D462"
  },
  "quote": {
    "fromTokenAmount": "100000000000000000",
    "toTokenAmount": "194058559",
    "estimatedGas": "1338000",
    "priceImpact": "-0.03",
    "tradeFee": "0.0174870969512694"
  },
  "inputToken": {
    "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
    "symbol": "ETH",
    "decimals": "18",
    "unitPrice": "1960.63"
  },
  "outputToken": {
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "symbol": "USDC",
    "decimals": "6",
    "unitPrice": "0.99989"
  },
  "unsignedTx": {
    "chainType": "evm",
    "from": "0x42a345F3d379B5060f0C36580bAF22C395B1D462",
    "to": "0x4409921ae43a39a11d90f7b96cfd0b8093d9fc",
    "data": "0xf2c42696...",
    "value": "100000000000000000",
    "gas": "1338000",
    "gasPrice": "10943011",
    "maxPriorityFeePerGas": "7301883"
  },
  "approval": {
    "isRequired": false,
    "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "spenderAddress": "0x57df6092665eb6058DE53939612413ff4B09114E",
    "requiredAmount": "10000000",
    "approveAmount": "10000000",
    "currentAllowance": "115792089237316195423570985008687907853269984665640564039457584007913129316681",
    "message": "Allowance is sufficient for spender 0x57df6092665eb6058DE53939612413ff4B09114E"
  }
}

Perpetual Trading Suggestion

post

Get AI-powered perpetual trading suggestions with long/short recommendations, entry price, stop loss, take profit levels, and confidence score based on comprehensive market analysis.

Authorizations

BearerAuth

AuthorizationstringRequired

Format: Authorization: Bearer <YOUR_API_KEY>

Body

application/json

symbolstringRequired

Required. Trading symbol (e.g., 'BTC', 'ETH', 'SOL').

stylestring · enumOptional

Optional. Trading style: 'scalping', 'day-trading', or 'swing-trading'. Default: 'scalping'.

Default: scalpingPossible values:

marginUSDnumberOptional

Optional. Margin in USD. Default: 1000.

Default: 1000

leveragenumber · min: 1 · max: 40Optional

Optional. Leverage multiplier (max: 40). Default: 10.

Default: 10

strategystringOptional

Optional. Strategy type. Default: 'max-profit'. More strategies coming soon.

Default: max-profit

Responses

200

Perpetual trading suggestion

application/json

entryPricenumberOptional

Recommended entry price.

sidestring · enumOptional

Trading side recommendation.

Possible values:

stopLossPricenumberOptional

Recommended stop loss price.

takeProfitPricenumberOptional

Recommended take profit price.

confidencenumber · max: 100Optional

Confidence score (0-100).

reasonsstring[]Optional

Analysis reasons based on technical indicators.

risksstring[]Optional

Risk factors to consider.

401

Unauthorized - Invalid or missing API key

post/v1/developer/perp-trading-suggestion

HTTPcURLJavaScriptPython

POST /v1/developer/perp-trading-suggestion HTTP/1.1
Host: api-developer.minara.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 91

{
  "symbol": "text",
  "style": "scalping",
  "marginUSD": 1000,
  "leverage": 10,
  "strategy": "max-profit"
}

{
  "entryPrice": 1,
  "side": "long",
  "stopLossPrice": 1,
  "takeProfitPrice": 1,
  "confidence": 1,
  "reasons": [
    "text"
  ],
  "risks": [
    "text"
  ]
}

Prediction Market Analysis

post

AI-powered prediction market analysis. Analyze prediction market events and get probability estimates for each outcome with detailed reasoning.

Authorizations

BearerAuth

AuthorizationstringRequired

Format: Authorization: Bearer <YOUR_API_KEY>

Body

application/json

linkstringRequired

Required. Prediction market page link (e.g., Polymarket event URL).

modestring · enumRequired

Required. Chat mode: 'fast' or 'expert'.

Possible values:

only_resultbooleanOptional

Optional. Only return prediction probabilities without reasoning. Default: false.

Default: false

customPromptstringOptional

Optional. Custom instructions to guide the analysis. Use this to specify focus areas, risk preferences, or analysis style.

Responses

200

Prediction market analysis

application/json

reasoningstringOptional

AI reasoning and analysis (empty if only_result=true).

401

Unauthorized - Invalid or missing API key

post/v1/developer/prediction-market-ask

HTTPcURLJavaScriptPython

POST /v1/developer/prediction-market-ask HTTP/1.1
Host: api-developer.minara.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "link": "text",
  "mode": "fast",
  "only_result": false,
  "customPrompt": "text"
}

{
  "predictions": [
    {
      "outcome": "text",
      "yesProb": 1,
      "noProb": 1
    }
  ],
  "reasoning": "text"
}

Фоновый чат и идемпотентность

Этот чат конечная точка выше поддерживает асинхронное выполнение и идемпотентные повторы через два необязательных поля: фоновый и requestId. Структуры запроса/ответа описаны в блоке OpenAPI выше; этот раздел охватывает правила поведения, которые схема не может выразить.

Фоновое выполнение

Установите background: true (действительно только с stream: false), чтобы запрос был принят немедленно (202 Accepted) и обработан асинхронно. Опросите конечную точку статуса (GET /v1/developer/chat/requests/{id}) с возвращенным id (или ваш requestId) background: true с stream: true возвращает 400 Bad Request.

Идемпотентность с requestId

requestId — это ключ, генерируемый клиентом, уникальный в пределах одного API-ключа, который позволяет безопасно повторить запрос без генерации (и оплаты) дублирующего результата. Работает в режимах синхронного выполнения, потоковой передачи и фонового режима.

• Один и тот же ключ, одна и та же полезная нагрузка → существующая задача повторно используется. Вы получаете ее текущий статус/результат вместо новой генерации. Если она все еще выполняется, вы получаете 202 Accepted; если она завершена, вы получаете 200 OK с результатом.
• Один и тот же ключ, другая полезная нагрузка → 409 Conflict ("requestId уже был использован с другим запросом").
• Повторное использование истекшего ключа → 409 Conflict ("requestId истек и не может быть повторно использован").

Для потоковых запросов, содержащих requestId, ответ включает X-Request-Id заголовок, генерация продолжается даже если клиент отключится, и окончательный результат можно позже получить через конечную точку статуса.

Примечания к статусу запроса чата

Конечная точка статуса (GET /v1/developer/chat/requests/{id}) принимает либо назначенный сервером id (например, bg_abc123), либо ваш requestId, и должна использовать тот же API-ключ, который создал задачу.

• Записи хранятся 24 часа после достижения конечного состояния (expiresAt), затем удаляются.
• Запрос, которого не существует или срок действия которого истек, возвращает 404 Not Found.
• Прерванные или превысившие тайм-аут задачи завершаются с ошибкой явно (они не повторяются автоматически). Код ошибки один из processing_error, processing_interrupted, processing_timeout. Отправьте новый запрос, чтобы повторить.