Справочник API

Справочник REST API Mockarty. Локально запущенный сервер доступен по адресу
http://127.0.0.1:5770, а Mockarty Desktop — по адресу http://127.0.0.1:5780.

Все тела запросов/ответов используют Content-Type: application/json, если не указано иное.

URL-адреса в примерах: Все примеры используют localhost:5770 как адрес по умолчанию. Если ваш Mockarty развёрнут на удалённом сервере (например, https://mockarty.company.com или http://192.168.1.50:5770), замените localhost:5770 на реальный адрес. SDK принимают базовый URL в конструкторе клиента, так что его достаточно указать один раз. Подробнее — в Быстром старте.

Совет: Если у примера есть вкладки, переключайтесь между cURL, CLI и SDK. Установка и подробное использование описаны в руководстве по SDK и руководстве по CLI.

Ваш первый мок

Создайте мок и вызовите его. Сначала создайте токен в разделе Настройки → API-токены и запишите его в MOCKARTY_API_KEY. У токена должно быть право создавать моки в пространстве sandbox.

cURL

# 1. Создаём мок
curl -X POST http://localhost:5770/api/v1/mocks \
  -H "X-API-Key: $MOCKARTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "hello-world",
    "namespace": "sandbox",
    "http": {
      "route": "/api/greeting",
      "httpMethod": "GET"
    },
    "response": {
      "statusCode": 200,
      "payload": {
        "message": "Hello, World!",
        "timestamp": "$.fake.RFC3339"
      }
    }
  }'

# 2. Вызываем мок (namespace — часть URL)
curl http://localhost:5770/stubs/sandbox/api/greeting
# Возвращает: {"message": "Hello, World!", "timestamp": "2026-03-22T10:30:00Z"}

CLI

# Установка: https://github.com/mockarty/mockarty-cli/releases

# 1. Сохраняем мок в файл и создаём его (пространство имён по умолчанию — "sandbox")
cat > hello-world.json <<'JSON'
{
  "id": "hello-world",
  "http": { "route": "/api/greeting", "httpMethod": "GET" },
  "response": { "statusCode": 200, "payload": { "message": "Hello, World!", "timestamp": "$.fake.RFC3339" } }
}
JSON
mockarty-cli mock create -f hello-world.json

# 2. Вызываем мок — namespace всегда часть URL
curl http://localhost:5770/stubs/sandbox/api/greeting

Go

// go get github.com/mockarty/mockarty-go

package main

import (
	"context"
	"fmt"
	"github.com/mockarty/mockarty-go"
)

func main() {
	// Пространство имён по умолчанию "sandbox"
	client := mockarty.NewClient("http://localhost:5770",
		mockarty.WithAPIKey("mk_YOUR_TOKEN"),
	)

	mock := mockarty.NewMockBuilder().
		ID("hello-world").
		HTTP(func(h *mockarty.HTTPBuilder) {
			h.Route("/api/greeting").Method("GET")
		}).
		Response(func(r *mockarty.ResponseBuilder) {
			r.Status(200).JSONBody(map[string]any{
				"message":   "Hello, World!",
				"timestamp": "$.fake.RFC3339",
			})
		}).
		Build()

	resp, err := client.Mocks().Create(context.Background(), mock)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Создан: %s (перезаписан: %v)\n", resp.Mock.ID, resp.Overwritten)
}

Python

# pip install mockarty

from mockarty import MockartyClient
from mockarty.builders import MockBuilder

# Пространство имён по умолчанию "sandbox"
client = MockartyClient(
    base_url="http://localhost:5770",
    api_key="mk_YOUR_TOKEN",
)

mock = (
    MockBuilder.http("/api/greeting", "GET")
    .id("hello-world")
    .respond(200, body={
        "message": "Hello, World!",
        "timestamp": "$.fake.RFC3339",
    })
    .build()
)

result = client.mocks.create(mock)
print(f"Создан: {result.mock.id}, перезаписан: {result.overwritten}")

Java

// Gradle: implementation "ru.mockarty:mockarty-java:0.3.0"

import ru.mockarty.MockartyClient;
import ru.mockarty.builder.MockBuilder;
import ru.mockarty.model.Mock;
import ru.mockarty.model.SaveMockResponse;
import java.util.Map;

// Пространство имён по умолчанию "sandbox"
try (MockartyClient client = MockartyClient.builder()
        .baseUrl("http://localhost:5770")
        .apiKey("mk_YOUR_TOKEN")
        .build()) {

    Mock mock = MockBuilder.http("/api/greeting", "GET")
        .id("hello-world")
        .respond(200, Map.of(
            "message", "Hello, World!",
            "timestamp", "$.fake.RFC3339"
        ))
        .build();

    SaveMockResponse resp = client.mocks().create(mock);
    System.out.println("Создан: " + resp.getMock().getId());
}

Kotlin

// Gradle: implementation("ru.mockarty:mockarty-kotlin:0.3.0")

import ru.mockarty.MockartyClient
import ru.mockarty.dsl.createMock

// Пространство имён по умолчанию "sandbox"
val client = MockartyClient.builder()
    .baseUrl("http://localhost:5770")
    .apiKey("mk_YOUR_TOKEN")
    .build()

client.createMock {
    id = "hello-world"
    http {
        route = "/api/greeting"
        method = "GET"
    }
    respond {
        statusCode = 200
        body = mapOf(
            "message" to "Hello, World!",
            "timestamp" to "$.fake.RFC3339"
        )
    }
}

Как это работает: Вы определяете мок через POST /api/v1/mocks, затем Mockarty обслуживает его по адресу /stubs/<ваш-маршрут>. Префикс /stubs указывает Mockarty разрешить мок, а не обращаться к API управления. Динамические значения вроде $.fake.RFC3339 подставляются в момент формирования ответа.

Если такой мок уже есть. Чтобы не затирать данные, создание мока с тем же методом и маршрутом (и условиями), который уже существует в пространстве имён, возвращает 409 с телом вида {"code":"duplicate_entity","matchLevel":"strict","existing":{"id":"…","summary":"GET /api/users"}} — вместо тихого создания дубля. Разрешите конфликт повтором запроса с query-параметром:

• ?intent=overwrite — заменить существующий мок на месте (его id сохраняется; это новая версия того же эндпоинта).
• ?intent=create_new — всё же создать второй мок (полезно, когда это действительно другой вариант, например другие условия совпадения или приоритет).

matchLevel — strict (идентичный мок) или similar (тот же эндпоинт с другими условиями). В интерфейсе появляется диалог Перезаписать / Создать новый / Отмена. То же работает при сохранении записанного UI-теста под уже существующим именем.

Содержание

1. Аутентификация
2. API управления моками (публичный)
3. API пространств имён
4. API хранилищ
5. API шаблонов
6. Руководство по CI/CD интеграции
7. API тестирования API
8. API нагрузочного тестирования
9. API фаззинга
10. API рекордера
11. API контрактного тестирования
12. API Chaos Engineering
13. API администрирования
14. Утилиты
15. Вызов HTTP-мока
16. Настройки автономных миссий пространства
17. Проверка знаний агентов
18. Окружения delivery policy (администратор)
19. Связанная документация

1. Аутентификация

Mockarty использует два механизма аутентификации: API-токены для программного доступа и сессионные куки для Web UI.

API-токены

Создавайте токены в Web UI (Настройки > API-токены) или через POST /api/v1/auth/tokens.

Передавайте токен в запросах через заголовок:

cURL

# Заголовок X-API-Key (пространство "sandbox" по умолчанию)
curl -H "X-API-Key: mk_YOUR_TOKEN" http://localhost:5770/api/v1/mocks

# Заголовок Authorization: Bearer
curl -H "Authorization: Bearer mk_YOUR_TOKEN" http://localhost:5770/api/v1/mocks

CLI

# Настройка токена и namespace глобально (сохраняется в ~/.mockarty-cli/config.yaml)
mockarty-cli config set-context default --token mk_YOUR_TOKEN --namespace sandbox
mockarty-cli config use-context default

# Или передать для конкретной команды
mockarty-cli mock list --token mk_YOUR_TOKEN

Go

// Токен задаётся через опцию WithAPIKey; пространство по умолчанию "sandbox"
client := mockarty.NewClient("http://localhost:5770",
    mockarty.WithAPIKey("mk_YOUR_TOKEN"),
    mockarty.WithNamespace("sandbox"), // необязательно, "sandbox" по умолчанию
)

Python

# Токен задаётся через параметр api_key; пространство по умолчанию "sandbox"
client = MockartyClient(
    base_url="http://localhost:5770",
    api_key="mk_YOUR_TOKEN",
    namespace="sandbox",  # необязательно, "sandbox" по умолчанию
)

Java

// Токен задаётся через apiKey; пространство по умолчанию "sandbox"
MockartyClient client = MockartyClient.builder()
    .baseUrl("http://localhost:5770")
    .apiKey("mk_YOUR_TOKEN")
    .namespace("sandbox")  // необязательно, "sandbox" по умолчанию
    .build();

Kotlin

// Токен задаётся через apiKey; пространство по умолчанию "sandbox"
val client = MockartyClient.builder()
    .baseUrl("http://localhost:5770")
    .apiKey("mk_YOUR_TOKEN")
    .namespace("sandbox")  // необязательно, "sandbox" по умолчанию
    .build()

Сессионная аутентификация

Для Web UI и доступа через браузер:

# Вход (возвращает сессионную куку)
curl -c cookies.txt -X POST http://localhost:5770/api/v1/auth/login \
  -d '{"username": "admin", "password": "secret"}'

# Использование сессионной куки
curl -b cookies.txt http://localhost:5770/api/v1/mocks

Эндпоинты аутентификации

Ограничение частоты запросов

Запросы к API ограничены в зависимости от лицензии. Лимиты применяются отдельно для каждого API-ключа.

2. API управления моками (публичный)

Эндпоинты для управления определениями моков. Доступны на корневом сервере (порт 5770). Требуют аутентификации с правом read или write.

Создание/обновление мока

POST /api/v1/mocks | Авторизация: пользователь (write)

Создаёт новый мок или перезаписывает существующий (по id).

cURL

curl -X POST http://localhost:5770/api/v1/mocks \
  -H "X-API-Key: mk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "get-user",
    "namespace": "sandbox",
    "http": {
      "route": "/api/users/list",
      "httpMethod": "GET"
    },
    "response": {
      "statusCode": 200,
      "payload": {
        "id": "$.fake.UUID",
        "name": "$.fake.FirstName",
        "email": "$.fake.Email"
      }
    }
  }'

CLI

# Пространство имён по умолчанию "sandbox"
echo '{"id":"get-user","http":{"route":"/api/users/list","httpMethod":"GET"},"response":{"statusCode":200,"payload":{"id": "$.fake.UUID", "name": "$.fake.FirstName", "email": "$.fake.Email"}}}' | mockarty-cli mock create -f -

Go

mock := mockarty.NewMockBuilder().
    ID("get-user").
    Namespace("sandbox"). // необязательно, "sandbox" по умолчанию
    HTTP(func(h *mockarty.HTTPBuilder) {
        h.Route("/api/users/list").Method("GET")
    }).
    Response(func(r *mockarty.ResponseBuilder) {
        r.Status(200).JSONBody(map[string]any{
            "id":    "$.fake.UUID",
            "name":  "$.fake.FirstName",
            "email": "$.fake.Email",
        })
    }).
    Build()

resp, err := client.Mocks().Create(context.Background(), mock)

Python

mock = (
    MockBuilder.http("/api/users/list", "GET")
    .id("get-user")
    .namespace("sandbox")  # необязательно, "sandbox" по умолчанию
    .respond(200, body={
        "id": "$.fake.UUID",
        "name": "$.fake.FirstName",
        "email": "$.fake.Email",
    })
    .build()
)

result = client.mocks.create(mock)

Java

Mock mock = MockBuilder.http("/api/users/list", "GET")
    .id("get-user")
    .namespace("sandbox")  // необязательно, "sandbox" по умолчанию
    .respond(200, Map.of(
        "id", "$.fake.UUID",
        "name", "$.fake.FirstName",
        "email", "$.fake.Email"
    ))
    .build();

SaveMockResponse resp = client.mocks().create(mock);

Kotlin

client.createMock {
    id = "get-user"
    namespace = "sandbox"  // необязательно, "sandbox" по умолчанию
    http {
        route = "/api/users/list"
        method = "GET"
    }
    respond {
        statusCode = 200
        body = mapOf(
            "id" to "$.fake.UUID",
            "name" to "$.fake.FirstName",
            "email" to "$.fake.Email"
        )
    }
}

Ответ:

{
  "overwritten": false,
  "mock": {
    "id": "get-user",
    "namespace": "default",
    "createdAt": 1704096000000,
    "useCounter": 0
  }
}

Полная структура мока (все поля необязательны, кроме id):

Структура условия (Condition)

Что такое условия? Условия позволяют возвращать разные ответы мока в зависимости от входящего запроса. Без условий мок соответствует любому запросу к его маршруту. С условиями Mockarty анализирует тело запроса, заголовки или параметры и выбирает мок только если все условия выполнены. Это полезно, когда несколько моков имеют один маршрут, но должны отвечать по-разному в зависимости от содержимого запроса (например, вернуть ошибку, когда $.status равен "invalid").

Массив conditions внутри конфигурационных объектов http, grpc и mcp управляет выбором мока. Каждое условие — объект со следующими полями:

Действия проверки (Assert actions):

Примечание: Устаревший псевдоним match также принимается и работает идентично matches.

Пример с расширенными полями условий:

{
  "id": "base64-body-mock",
  "http": {
    "route": "/api/validate",
    "httpMethod": "POST",
    "conditions": [
      {
        "path": "$.encodedData",
        "assertAction": "contains",
        "value": "expected-content",
        "decode": "base64"
      },
      {
        "path": "$.items",
        "assertAction": "equals",
        "value": ["b", "a", "c"],
        "sortArray": true
      },
      {
        "path": "$.payload",
        "assertAction": "equals",
        "valueFromFile": "/templates/expected-payload.json"
      }
    ]
  },
  "response": {
    "statusCode": 200,
    "payload": {"status": "validated"}
  }
}

Примечание: decode, sortArray и valueFromFile — поля только для API, они не доступны в визуальном конструкторе Web UI.

Получение мока

GET /api/v1/mocks/:id | Авторизация: пользователь (read)

cURL

curl -H "X-API-Key: mk_YOUR_TOKEN" http://localhost:5770/api/v1/mocks/get-user

CLI

mockarty-cli mock get get-user

Go

mock, err := client.Mocks().Get(context.Background(), "get-user")

Python

mock = client.mocks.get("get-user")

Java

Mock mock = client.mocks().get("get-user");

Kotlin

val mock = client.mocks().get("get-user")

Список моков

GET /api/v1/mocks | Авторизация: пользователь (read)

cURL

# Пространство "sandbox" по умолчанию
curl -H "X-API-Key: mk_YOUR_TOKEN" \
  "http://localhost:5770/api/v1/mocks?namespace=sandbox&protocol=http&onlyActive=true&limit=10"

CLI

mockarty-cli mock list --namespace sandbox

Go

page, err := client.Mocks().List(context.Background(), &mockarty.ListMocksOptions{
    Namespace: "sandbox", // необязательно, "sandbox" по умолчанию
    Protocol:  "http",
    Limit:     10,
    OnlyActive: true,
})
for _, m := range page.Items {
    fmt.Println(m.ID)
}

Python

page = client.mocks.list(namespace="sandbox", protocol="http", only_active=True, limit=10)
for mock in page.items:
    print(mock.id)

Java

Page<Mock> page = client.mocks().list(
    "sandbox", null, null, null, "http", true, 0, 10);
for (Mock m : page.getItems()) {
    System.out.println(m.getId());
}

Kotlin

val page = client.mocks().list(
    "sandbox", null, null, null, "http", true, 0, 10)
page.items.forEach { println(it.id) }

Удаление мока (мягкое)

DELETE /api/v1/mocks/:id | Авторизация: пользователь (delete)

cURL

curl -X DELETE -H "X-API-Key: mk_YOUR_TOKEN" \
  http://localhost:5770/api/v1/mocks/get-user

CLI

mockarty-cli mock delete get-user

Go

err := client.Mocks().Delete(context.Background(), "get-user")

Python

client.mocks.delete("get-user")

Java

client.mocks().delete("get-user");

Kotlin

client.mocks().delete("get-user")

Восстановление мока

Восстановить мягко удалённый мок (один или несколько) из корзины:

POST /api/v1/mocks/batch/restore | Авторизация: пользователь (write)

{ "ids": ["mock_123"] }

Полное удаление мока

DELETE /api/v1/mocks/:id/purge | Авторизация: пользователь (delete)

Журналы запросов мока

GET /api/v1/mocks/:id/logs | Авторизация: пользователь (read)

Возвращает историю запросов к моку.

{
  "id": "get-user",
  "requests": [
    {
      "calledAt": "2024-01-01T10:05:00Z",
      "req": {
        "header": {},
        "body": {},
        "queryParam": {},
        "url": "/stubs/api/users/123"
      }
    }
  ]
}

Цепочки моков

Пакетное создание

POST /api/v1/mocks/batch | Авторизация: пользователь (write)

Создание нескольких моков за один запрос.

cURL

curl -X POST http://localhost:5770/api/v1/mocks/batch \
  -H "X-API-Key: mk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {"id": "mock-1", "namespace": "sandbox", "http": {"route": "/api/a", "httpMethod": "GET"}, "response": {"statusCode": 200}},
    {"id": "mock-2", "namespace": "sandbox", "http": {"route": "/api/b", "httpMethod": "GET"}, "response": {"statusCode": 200}}
  ]'

CLI

# Пакетное создание из JSON-файла (пространство по умолчанию "sandbox")
mockarty-cli mock create --file mocks.json

Go

mocks := []*mockarty.Mock{
    mockarty.NewMockBuilder().ID("mock-1").
        HTTP(func(h *mockarty.HTTPBuilder) { h.Route("/api/a").Method("GET") }).
        Response(func(r *mockarty.ResponseBuilder) { r.Status(200) }).
        Build(),
    mockarty.NewMockBuilder().ID("mock-2").
        HTTP(func(h *mockarty.HTTPBuilder) { h.Route("/api/b").Method("GET") }).
        Response(func(r *mockarty.ResponseBuilder) { r.Status(200) }).
        Build(),
}

err := client.Mocks().BatchCreate(context.Background(), mocks)

Python

mocks = [
    MockBuilder.http("/api/a", "GET").id("mock-1").respond(200).build(),
    MockBuilder.http("/api/b", "GET").id("mock-2").respond(200).build(),
]

results = client.mocks.batch_create(mocks)

Java

// В Java SDK нет отдельного метода batchCreate;
// используйте цикл для создания каждого мока по отдельности
Mock mock1 = MockBuilder.http("/api/a", "GET").id("mock-1").respond(200).build();
Mock mock2 = MockBuilder.http("/api/b", "GET").id("mock-2").respond(200).build();

client.mocks().create(mock1);
client.mocks().create(mock2);

Частичное обновление (Patch)

PATCH /api/v1/mocks/:id | Авторизация: пользователь (write)

Частичное обновление мока (переданные поля объединяются с существующим моком).

cURL

curl -X PATCH http://localhost:5770/api/v1/mocks/get-user \
  -H "X-API-Key: mk_YOUR_TOKEN" \
  -d '{"response": {"statusCode": 201}}'

CLI

# CLI не предоставляет отдельной команды patch.
# Экспортируйте мок, отредактируйте его локально и примените полное определение —
# сервер обновит существующий мок по id.
mockarty-cli mock get get-user -o json > mock.json
# отредактируйте mock.json (например, измените response.statusCode на 201)
mockarty-cli mock create -f mock.json

Go

updated, err := client.Mocks().Patch(context.Background(), "get-user", map[string]any{
    "response": map[string]any{"statusCode": 201},
})

Python

updated = client.mocks.patch("get-user", {"response": {"statusCode": 201}})

Java

Mock updated = client.mocks().patch("get-user", Map.of(
    "response", Map.of("statusCode", 201)
));

История версий мока

Предпросмотр разрешения мока

GET /api/v1/mocks/preview | Авторизация: пользователь (read)

Предпросмотр того, какой мок будет разрешён для указанного маршрута/метода без фактического вызова stub-эндпоинта.

Пакетные операции (UI API)

Теги

Папки моков

Организация моков в папки для удобного управления.

Неопределённые запросы

Перехваченные запросы, не совпавшие ни с одним моком.

Активные протоколы плагинов

GET /api/v1/plugin-protocols | Авторизация: пользователь (mock:read)

Возвращает протокольные кодеки плагинов, активные в запрошенном namespace. В
каждой строке есть точный Socket serverName; при создании мока используйте его
без изменений. Сам wire-listener доступен, только если сервер запущен с
MOCKARTY_UNIFIED_PORT=1.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:5770/api/v1/plugin-protocols?namespace=sandbox"

catalogue, err := client.Mocks().ListPluginProtocols(ctx, "sandbox")

catalogue = client.mocks.list_plugin_protocols(namespace="sandbox")

PluginProtocolCatalogue catalogue = client.mocks().listPluginProtocols("sandbox");

Тот же каталог доступен агентам через read-only MCP-инструмент
plugin_protocols_list и в CLI как mockarty-cli plugin protocols.

Примеры протокольных моков (GraphQL / SOAP / gRPC)

Моки — не только HTTP. Тот же POST /api/v1/mocks принимает блок конфига
протокола (graphql, soap, grpc, …) вместо http. response.payload и
шаблонные плейсхолдеры ($.fake.*, $.req.*) работают во всех протоколах.
Все три примера ниже выверены end-to-end.

GraphQL — матч по operation + field, отдаётся поверх HTTP по graphql.path:

# Создать
curl -X POST "http://localhost:5770/api/v1/mocks?namespace=sandbox" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "id": "gql-user",
    "graphql": { "operation": "query", "field": "user", "path": "/graphql" },
    "response": { "statusCode": 200, "payload": { "data": { "user": { "id": "$.fake.UUID", "name": "Ada" } } } }
  }'

# Вызвать
curl -X POST http://localhost:5770/stubs/sandbox/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"query { user { id name } }"}'
# → {"data":{"user":{"id":"2778f790-…","name":"Ada"}}}

SOAP — матч по service / method / action, отдаётся по soap.path.
Для XML положите сырой envelope в response.payload как строку:

# Создать
curl -X POST "http://localhost:5770/api/v1/mocks?namespace=sandbox" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "id": "soap-getuser",
    "soap": { "service": "UserService", "method": "GetUser", "action": "GetUser", "path": "/soap/users" },
    "response": {
      "statusCode": 200,
      "payload": "<soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"><soap:Body><GetUserResponse><id>42</id><name>Ada</name></GetUserResponse></soap:Body></soap:Envelope>",
      "headers": { "Content-Type": ["text/xml"] }
    }
  }'

# Вызвать
curl -X POST http://localhost:5770/stubs/sandbox/soap/users \
  -H "Content-Type: text/xml" -H "SOAPAction: GetUser" \
  -d '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><GetUser><id>42</id></GetUser></soap:Body></soap:Envelope>'
# → envelope GetUserResponse выше

gRPC — матч по service / method. Сначала загрузите .proto сервиса
(Admin → gRPC или POST /api/v1/api-tester/import/grpc), затем создайте мок:

# Создать
curl -X POST "http://localhost:5770/api/v1/mocks?namespace=sandbox" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "id": "grpc-getuser",
    "grpc": { "service": "user.UserService", "method": "GetUser" },
    "response": { "statusCode": 0, "payload": { "id": "42", "name": "Ada" } }
  }'

# Вызвать любым gRPC-клиентом (gRPC-порт по умолчанию :5773), напр. grpcurl:
grpcurl -plaintext -d '{"id":"42"}' localhost:5773 user.UserService/GetUser

SSE — матч по sse.eventPath; ответ стримит события из
response.sseEventChain.events[]. Запрос считается SSE, если несёт
Accept: text/event-stream (или путь под /sse/ либо /events/):

# Создать
curl -X POST "http://localhost:5770/api/v1/mocks?namespace=sandbox" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "id": "sse-orders",
    "sse": { "eventPath": "/events/orders", "eventName": "order" },
    "response": { "sseEventChain": { "events": [
      { "eventName": "order", "data": { "id": "$.fake.UUID", "status": "created" }, "delay": 100 },
      { "eventName": "order", "data": { "status": "shipped" }, "delay": 100 }
    ] } }
  }'

# Вызвать (стрим)
curl -N -H "Accept: text/event-stream" http://localhost:5770/stubs/sandbox/events/orders
# → event:order
#   data:{"id":"ccdc58b8-…","status":"created"}
#   event:order
#   data:{"status":"shipped"}

WebSocket — матч по socket.serverName + socket.event:

# Создать
curl -X POST "http://localhost:5770/api/v1/mocks?namespace=sandbox" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "id": "ws-echo",
    "socket": { "serverName": "chat", "event": "message" },
    "response": { "payload": { "reply": "pong", "at": "$.fake.RFC3339" } }
  }'

# Вызвать любым WebSocket-клиентом (напр. websocat):
websocat ws://localhost:5770/stubs/sandbox/chat

MCP — матч по mcp.method (tools/call) + mcp.tool. Мок публикуется
как инструмент на MCP-сервере пространства имён и вызывается по JSON-RPC. Мок без
pathPrefix отдаётся по базе namespace (/stubs/<ns>); чтобы отдавать под
суб-путём, задайте pathPrefix (напр. "/mcp") и зовите /stubs/<ns>/mcp.
Полный флоу сервера — в MCP Marketplace.

# Создать
curl -X POST "http://localhost:5770/api/v1/mocks?namespace=sandbox" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "id": "mcp-weather",
    "mcp": { "method": "tools/call", "tool": "get_weather", "description": "Get weather" },
    "response": { "payload": { "temp": 21, "city": "Berlin" } }
  }'

# Вызвать по JSON-RPC на базе namespace (у мока нет pathPrefix)
curl -X POST http://localhost:5770/stubs/sandbox \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_weather","arguments":{}}}'
# → {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"temp\":21,\"city\":\"Berlin\"}"}],"isError":false}}

Так же мокаются промпты MCP: mcp.method prompts/get + mcp.prompt (имя
промпта). Тело ответа — результат промпта: messages с role (user или
assistant) и text либо просто строка — одно сообщение пользователя;
$.req.<аргумент> подставляет аргумент вызова. Список arguments в теле — то, что
клиент видит в prompts/list (в ответ prompts/get он не попадает). Условия на
аргументы выбирают между несколькими моками одного промпта. Как только у пути сервера
появляется мок-промпт, initialize объявляет возможность prompts.

curl -X POST "http://localhost:5770/api/v1/mocks?namespace=sandbox" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "id": "mcp-review-prompt",
    "pathPrefix": "/prompts-demo",
    "mcp": { "method": "prompts/get", "prompt": "code_review", "description": "Review a diff" },
    "response": { "payload": {
      "arguments": [{ "name": "diff", "description": "Unified diff", "required": true }],
      "messages": [{ "role": "user", "text": "Review this change: $.req.diff" }]
    } }
  }'

curl -X POST http://localhost:5770/stubs/sandbox/prompts-demo \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"prompts/get","params":{"name":"code_review","arguments":{"diff":"+ retry on 503"}}}'
# → {"id":3,"jsonrpc":"2.0","result":{"messages":[{"content":{"text":"Review this change: + retry on 503","type":"text"},"role":"user"}]}}

В конструкторе мока выберите Тип запроса → Промпт (prompts/get) и введите имя
промпта; вызов неизвестного промпта попадает в Неопределённые запросы, откуда его
можно превратить в мок-промпт.

S3 — Mockarty эмулирует S3-совместимое объектное хранилище по бакету. Объявите
бакет через s3.bucket, затем используйте любой S3-клиент (или plain path-style
HTTP под /stubs/<ns>/<bucket>/<key>, включая aws s3 --no-sign-request):

# Создать мок бакета
curl -X POST "http://localhost:5770/api/v1/mocks?namespace=sandbox" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "id": "s3-assets", "s3": { "bucket": "assets" } }'

# PUT затем GET объекта (path-style, анонимно)
curl -X PUT  http://localhost:5770/stubs/sandbox/assets/greeting.txt --data 'hello from s3 mock'
curl http://localhost:5770/stubs/sandbox/assets/greeting.txt
# → hello from s3 mock

Kafka / RabbitMQ / SMTP — асинхронные моки. Mockarty матчит входящее сообщение
(Kafka-record / AMQP-сообщение / письмо) против конфига + условий и может
опубликовать ответ в output* topic/queue. Мок создаётся так же; вызывается
продюсингом в матчируемый topic/queue или отправкой письма на настроенный сервер
(не по HTTP):

# Kafka — матч topic 'orders', ответ публикуется в настроенный output-topic
curl -X POST "http://localhost:5770/api/v1/mocks?namespace=sandbox" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "id": "kafka-orders", "kafka": { "topic": "orders", "serverName": "prod" }, "response": { "payload": { "status": "ack" } } }'

# RabbitMQ — матч queue 'tasks'
curl -X POST "http://localhost:5770/api/v1/mocks?namespace=sandbox" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "id": "rmq-tasks", "rabbitmq": { "queue": "tasks", "serverName": "prod" }, "response": { "payload": { "status": "ack" } } }'

# SMTP — матч писем, у которых subject содержит 'Welcome'
curl -X POST "http://localhost:5770/api/v1/mocks?namespace=sandbox" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "id": "smtp-welcome", "smtp": { "serverName": "mail", "subjectConditions": [ { "assertAction": "contains", "value": "Welcome" } ] }, "response": { "payload": { "accepted": true } } }'

3. API пространств имён

Как читать ответ со списком

Эндпоинт списка возвращает строки под ключом, названным по сущности, рядом со счётчиком:

{ "count": 2, "mocks": [{ "id": "mock_1785…", "name": "users" }] }

{ "total": 7, "limit": 50, "offset": 0, "runs": [{ "id": "7e8ef264-…", "status": "running" }] }

Для общих коллекций, где имя сущности ничего не добавляет, используется items:

{ "count": 3, "items": [{ "id": "37abcf01-…", "name": "Chrome / Linux" }] }

Счётчик называется count для полного набора и total, когда ответ постраничный (тогда
присутствуют и limit / offset). Какой ключ у конкретного эндпоинта — смотрите в его
разделе; источник истины — схема Swagger (/swagger/index.html), она всегда совпадает с
запущенной сборкой.

Эндпоинт списка никогда не возвращает null вместо строк — пустой результат это пустой
массив, поэтому итерироваться можно без проверки на nil.

Как указать пространство имён в любом эндпоинте

Любой эндпоинт, работающий внутри пространства имён, принимает его в любой из форм —
выберите удобную вашему клиенту и придерживайтесь её:

# Параметром запроса
curl "http://localhost:5770/api/v1/test-cases?namespace=staging" -H "X-API-Key: $TOKEN"

# Сегментом пути
curl "http://localhost:5770/api/v1/namespaces/staging/test-cases" -H "X-API-Key: $TOKEN"

# Заголовком (удобно, когда клиент проставляет его один раз для всех запросов)
curl "http://localhost:5770/api/v1/test-cases" \
  -H "X-Mockarty-Namespace: staging" -H "X-API-Key: $TOKEN"

Все три формы попадают в один и тот же обработчик и возвращают одинаковый результат. Если
ваш токен закреплён за пространством имён, можно не указывать его вовсе — будет использовано
закреплённое.

Доступ проверяется одинаково при любой форме: нужно быть участником указанного пространства
имён. Обращение к чужому вернёт 404, а не 403, — чтобы по ответу нельзя было выяснить,
какие пространства имён существуют.

Пример копирования моков:

cURL

curl -X POST -H "X-API-Key: mk_YOUR_TOKEN" \
  http://localhost:5770/api/v1/mocks/copy-to-namespace \
  -d '{
    "sourceNamespace": "staging",
    "targetNamespace": "production",
    "mockIds": ["mock-1", "mock-2"]
  }'

Go

err := client.Mocks().CopyToNamespace(context.Background(),
    []string{"mock-1", "mock-2"}, "production",
)

Python

client.mocks.copy_to_namespace(
    ids=["mock-1", "mock-2"],
    target_namespace="production",
)

Java

client.mocks().copyToNamespace(
    List.of("mock-1", "mock-2"),
    "production"
);

4. API хранилищ

Три типа хранилищ для моков с состоянием. Подробнее в Системе хранилищ.

Глобальное хранилище

Каждый POST-запрос добавляет одну пару ключ-значение. Для добавления нескольких ключей выполните отдельные запросы.

cURL

# Установить пару ключ-значение (один за запрос)
curl -X POST -H "X-API-Key: mk_YOUR_TOKEN" \
  "http://localhost:5770/api/v1/stores/global" \
  -d '{"key": "totalUsers", "value": "100", "namespace": "sandbox"}'

curl -X POST -H "X-API-Key: mk_YOUR_TOKEN" \
  "http://localhost:5770/api/v1/stores/global" \
  -d '{"key": "serviceName", "value": "auth", "namespace": "sandbox"}'

# Прочитать хранилище
curl -H "X-API-Key: mk_YOUR_TOKEN" \
  "http://localhost:5770/api/v1/stores/global?namespace=sandbox"

# Удалить ключ (ключ в URL-пути)
curl -X DELETE -H "X-API-Key: mk_YOUR_TOKEN" \
  "http://localhost:5770/api/v1/stores/global/totalUsers?namespace=sandbox"

CLI

# Установить значение (пространство по умолчанию "sandbox")
mockarty-cli store global set totalUsers 100
mockarty-cli store global set serviceName auth

# Прочитать хранилище
mockarty-cli store global get

# Удалить ключ
mockarty-cli store global delete totalUsers

Go

// Установить значения (используется пространство клиента по умолчанию "sandbox")
err := client.Stores().GlobalSet(context.Background(), "totalUsers", 100)
err = client.Stores().GlobalSet(context.Background(), "serviceName", "auth")

// Прочитать хранилище
store, err := client.Stores().GlobalGet(context.Background())
fmt.Println(store) // map[totalUsers:100 serviceName:auth ...]

// Удалить ключ
err = client.Stores().GlobalDelete(context.Background(), "totalUsers")

Python

# Установить значения (используется пространство клиента по умолчанию "sandbox")
client.stores.global_set("totalUsers", 100)
client.stores.global_set("serviceName", "auth")

# Или установить несколько значений за раз
client.stores.global_set_many({"totalUsers": 100, "serviceName": "auth"})

# Прочитать хранилище
store = client.stores.global_get()
print(store)  # {"totalUsers": 100, "serviceName": "auth"}

# Удалить ключи
client.stores.global_delete("totalUsers")

Java

// Установить значения (используется пространство клиента по умолчанию "sandbox")
client.stores().globalSet("totalUsers", 100);
client.stores().globalSet("serviceName", "auth");

// Прочитать хранилище
Map<String, Object> store = client.stores().globalGet();
System.out.println(store);

// Удалить ключ
client.stores().globalDelete("totalUsers");

Хранилище цепочки

5. API шаблонов

Загрузка шаблонов ответов для использования в моках через payloadTemplatePath.

Временное хранилище файлов

Временная загрузка файлов для использования в интерфейсе чата с агентом. Файлы автоматически удаляются через 30 минут.

Временные файлы доступны только загрузившему их пользователю или сервисному ключу и в выбранном namespace. Для чтения, удаления и импорта используйте ту же идентичность и namespace. Файлы истекают через 30 минут. При Redis файлы доступны на разных admin-узлах; InMemory хранит их на принявшем узле. Если включено шифрование данных, оно защищает содержимое и имена общих временных файлов. При заполнении хранилища возвращается 429, при его недоступности — 503. Не повторяйте импорт автоматически после неопределённого ответа.

Генерация из OpenAPI (сокращённая форма)

6. Руководство по CI/CD интеграции

Пошаговые примеры перенесены в «API-автоматизацию в CI/CD»: API-тесты, нагрузка, фаззинг, импорт и подготовка моков.

7. API тестирования API

Полнофункциональная платформа тестирования API (аналог Postman). Все эндпоинты под /api/v1/ и требуют аутентификации.

Коллекции

Примечание: POST /api/v1/api-tester/collections принимает необязательный query-параметр ?namespace=. Без него — и без заголовка X-Mockarty-Namespace или токена, закреплённого за namespace, — коллекция молча создаётся в namespace по умолчанию sandbox. Автоматизации следует всегда передавать ?namespace= явно, чтобы коллекции не оседали там, где их трудно найти.

Совместный доступ к коллекциям

Пока коллекция находится в корзине, изменения доступа отклоняются. Удаление или изменение несуществующего доступа пользователя возвращает 404.

Прямой доступ пользователю можно выдать только действующему участнику
Пространства коллекции с включённой учётной записью. Шаринг не приглашает в
Team, не добавляет место и не возвращает доступ после исключения из
Пространства. Сначала пригласите коллегу. Целевое Пространство также должно
быть доступно тому, кто выдаёт доступ; наблюдатель не может выдать право
редактирования. Отзыв или отключение членства закрывает и прежние права.

Для поиска людей и получения профилей по ID нужно явно указать Пространство,
которое вызывающий пользователь может читать:

Вместо query-параметра можно использовать X-Mockarty-Namespace или токен,
закреплённый за этим Пространством. Без явного контекста возвращается 400;
доступ к Пространству проверяется до выдачи профилей. Ответ содержит users
с полями id, username, fullName и, при наличии, email и avatarUrl.
Неизвестные, чужие, отключённые и удалённые ID пропускаются: ответ не
подтверждает существование глобальной учётной записи. Это не каталог для
поиска и приглашения незнакомых пользователей.

Запросы

Окружения

Запуски тестов

Режимы единой витрины запусков

Каждая строка из /api/v1/api-tester/test-runs содержит поле mode,
идентифицирующее источник запуска:

Примеры фильтрации:

# Все fuzz-кампании в namespace
curl -H "Authorization: Bearer $TOKEN" \
  "$MOCKARTY_URL/api/v1/api-tester/test-runs?mode=fuzz"

# Все запуски конкретного chaos-эксперимента
curl -H "Authorization: Bearer $TOKEN" \
  "$MOCKARTY_URL/api/v1/api-tester/test-runs?mode=chaos&referenceId=$EXPERIMENT_ID"

# Пагинация по функциональным запускам
curl -H "Authorization: Bearer $TOKEN" \
  "$MOCKARTY_URL/api/v1/api-tester/test-runs?mode=functional&limit=50&offset=100"

Эквиваленты в SDK:

// Go
runs, err := client.TestRuns.ListWithOptions(ctx, mockarty.ListTestRunsOptions{
    Mode:        "fuzz",
    ReferenceID: fuzzConfigID,
    Limit:       50,
})

# Python
runs = client.test_runs.list(mode="chaos", reference_id=experiment_id, limit=50)

// Java
List<TestRun> runs = client.testRuns().listByMode("fuzz", fuzzConfigId, 50, 0);

# CLI
mockarty-cli test-runs list --mode chaos --reference-id "$EXPERIMENT_ID" --limit 50

Скрипты и выполнение

Для execute-perf передайте collectionIds сохранённых коллекций или элементы selection с collectionId и необязательным requestIds, чтобы выполнить определённые запросы. Замените ID коллекции в примере своим:

{
  "collectionIds": ["00000000-0000-4000-8000-000000000001"],
  "perfOptions": {"vus": 20, "duration": "1m", "rps": 100},
  "useSSE": true
}

Без perfOptions используются 10 виртуальных пользователей и длительность 30 секунд. rps: 0 запускает тест без заданной частоты запросов. Необязательные поля: name, environmentId, environmentVariables, runnerId (предпочтительный раннер), ciTriggerId (сохранённый CI-триггер) и isDebug. Без полей окружения используется ваше активное окружение. Непустой объект environmentVariables заменяет значения окружения для этого запуска; явно указанный environmentId всё равно должен быть доступен. Для выбора раннера или CI нужен доступный сервис выполнения; иначе API возвращает HTTP 503.

Запуски через очередь возвращают HTTP 202 с taskId и status: "queued". Локальный запуск возвращает события SSE при useSSE: true или завершённый объект testRun в остальных случаях. isDebug: true выполняет тест без сохранения запуска в историю. Генерация нагрузки из коллекции поддерживает HTTP, GraphQL и SOAP; для включённых скриптов запроса, скриптов коллекции, multipart и двоичных тел нужен отдельный нагрузочный скрипт. Необработанное исключение скрипта помечает нагрузочный запуск как неуспешный; HTTP-метрики отражают только реальные запросы.

Коллекции, открытые из другого Space, можно просматривать и копировать, но нельзя выполнять в Space получателя. Отправка сохранённого запроса, запуск его скриптов, функциональный или нагрузочный запуск коллекции и создание расписания возвращают HTTP 403. Перед выполнением скопируйте коллекцию в свой Space. Коллекции с общим доступом внутри одного Space по-прежнему можно выполнять.

При копировании коллекции сохраняются её скрипты и шаблоны. После копирования в ваше Пространство они могут использовать его переменные и секреты при запуске. Перед запуском проверьте скопированную коллекцию.

Создание моков из коллекции также требует доступа к ней в вашем Space. Недоступный ID коллекции возвращает HTTP 404, общая коллекция из другого Space — HTTP 403 до чтения её запросов или истории.

Если сохранённый запрос выполняется в браузере, POST /api/v1/api-tester/scripts/execute принимает {"scriptType":"preRequest","requestId":"<id>","authorizeOnly":true} для проверки доступа без выполнения. При разрешённом доступе возвращается {"success":true}, для общей коллекции из другого Space — HTTP 403, для недоступного запроса — HTTP 404. Скрипты не запускаются, история не создаётся.

Вердикт скрипта содержит status (passed, failed, skipped или error), success, totalTests, passedTests, failedTests и skippedTests. При упавшей проверке success равен false, даже если JavaScript выполнился без исключения. /scripts/execute возвращает tests, logs и durationMs непосредственно; автономные тесты сохраняют объект result и поле duration в миллисекундах. Для проверки сохранённого запроса передайте requestId, чтобы использовать контекст его коллекции. Результат выполнения может содержать skipRequest: true, если скрипт до отправки пропустил запрос.

Для выполнения в браузере по этапам передайте executionMode: "client". Этап до отправки возвращает подготовленный requestData и scriptState; передайте это состояние этапу проверок вместе с фактическим responseData. Состояние содержит environmentId, environment, collectionVariables, requestVariables и runContext; его размер ограничен 1 МиБ. Пустой environmentId сохраняет выполнение без окружения. Оба этапа используют исходное окружение, даже если активный выбор изменился во время запроса. preScriptEnabled и testScriptEnabled управляют собственными фрагментами запроса; скрипты коллекции продолжают выполняться. Обычный предпросмотр скрипта выполняется отдельно и не сохраняет изменения окружения.

Автономные тесты

Расписания (Cron)

Чтение, изменение, удаление и ручной запуск расписания разрешены только его
владельцу в текущем пространстве. При создании, изменении и запуске Mockarty
также проверяет доступ владельца ко всем указанным коллекциям и окружению.
Неизвестный или недоступный ресурс не раскрывается. Если проверить доступ
невозможно из-за недоступности хранилища данных, запрос записи или запуска
возвращает 503 и не начинает работу. Перед автоматическим запуском доступ
проверяется повторно, поэтому отзыв доступа к коллекции блокирует отправку.

Импорт/экспорт

При импорте нативной коллекции Mockarty код 200 означает, что все элементы сохранены. Код 207 означает, что часть запросов или папок не сохранилась; содержимое несохранённой папки также пропускается. summary.failedCount показывает полное число, а failures содержит до 50 элементов. Прежний requestsCount учитывает все сохранённые строки, включая папки; summary.importedRequests учитывает только запросы. В ответе остаются collectionId и сохранённые элементы; проверьте их перед повторным импортом.

Вспомогательные эндпоинты протоколов

Прокси MCP проверяет адрес до запроса и при сетевом подключении, в том числе после перенаправлений. Доступ к частным адресам зависит от настроек сервера; адреса облачных метаданных остаются закрытыми.

Kafka Admin

RabbitMQ Admin

8. API нагрузочного тестирования

Встроенное нагрузочное тестирование с k6-совместимыми скриптами. Все эндпоинты под /api/v1/.

Конфигурации нагрузочных тестов

Запуск/остановка тестов

Результаты

Расписания

Задачи раннеров

Для type: "performance" запрос POST /api/v1/runner-tasks требует configId. Сохранённая конфигурация должна принадлежать пространству вызывающего пользователя; Mockarty выполняет её скрипт и окружение, а необязательный объект options в запросе заменяет сохранённые параметры прогона. Для разовых inline-скриптов используйте высокоуровневое API нагрузочного тестирования.

9. API фаззинга

Фаззинг безопасности со встроенными категориями полезных нагрузок (SQL-инъекции, XSS и др.). Все эндпоинты под /api/v1/fuzzing/.

Сводка и полезные нагрузки

Конфигурации

Импорт

Обнаружение протоколов

Запуски и результаты

аномалии

Расписания

10. API рекордера

Запись HTTP-трафика (на основе прокси). Все эндпоинты под /api/v1/recorder/.

Сессии

Пример начала сессии:

cURL

curl -X POST "$BASE/recorder/start" \
  -H "X-API-Key: $TOKEN" \
  -d '{
    "targetUrl": "https://api.example.com",
    "port": 8888,
    "name": "API Recording"
  }'

Go

session, err := client.Recorder().StartRecording(context.Background(), &mockarty.RecorderSession{
    TargetURL: "https://api.example.com",
    Port:      8888,
    Name:      "API Recording",
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Сессия запущена: %s\n", session.ID)

Python

session = client.recorder.start_recording({
    "targetUrl": "https://api.example.com",
    "port": 8888,
    "name": "API Recording",
})
print(f"Сессия запущена: {session.id}")

Java

RecorderSession session = client.recorder().startRecording(Map.of(
    "targetUrl", "https://api.example.com",
    "port", 8888,
    "name", "API Recording"
));
System.out.println("Сессия запущена: " + session.getId());

Совет: Те же операции доступны через mockarty-cli recorder ... — справочник команд см. в Руководстве CLI.

Записи

Модификации (перезапись запросов/ответов)

Экспорт

AI-анализ

Конфигурация

WebSocket

11. API контрактного тестирования

Контрактное тестирование проверяет, что ваши моки остаются согласованными со спецификациями реальных API. Поддерживаются: валидация по OpenAPI, потребительские контракты (совместимость с Pact), обнаружение дрейфа API (API drift) и реестр API (внутренний маркетплейс). Все эндпоинты находятся под префиксом /api/v1/contract/.

Валидация моков

Конфигурации и регулярные запуски

Результаты и тренды

аномалии (AI-анализ)

Потребительские контракты (Pact)

Реестр API (внутренний маркетплейс)

Подписки

12. API Chaos Engineering

Kubernetes-нативный chaos engineering для инъекции отказов и проверки отказоустойчивости. Создавайте эксперименты для внесения отказов (убийство подов, сетевые задержки, нагрузка на ресурсы) в ваши кластеры и наблюдайте за поведением сервисов. Все эндпоинты находятся под префиксом /api/v1/chaos/.

Пресеты

Эксперименты

Очередь экспериментов

Инфраструктурные профили

Chaos Operator

Ресурсы Kubernetes

13. API администрирования

Эндпоинты только для администраторов (роль admin). Префикс: /api/v1/admin/.

Управление пользователями

Управление пространствами имён (Админ)

Политики очистки

Настройки LLM/AI

Каждая строка стоимости по валюте несёт commercialTermsApplied. Значение
false означает, что ни платформенный сбор, ни наценка, ни налог, ни скидка в
этой сводке не применялись: стоимость для клиента равна провайдерской, и строка
записывает, во что работа обошлась, а не за сколько продана. Про равенство сумм
признак ничего не утверждает: возврат пишет отрицательную клиентскую стоимость
без коммерческих компонентов, поэтому в области с возвратами клиентская сумма
ниже, а признак остаётся false.

Каждая строка бюджета несёт softLimitBreached, вычисляемый на чтении из
потраченного плюс зарезервированного. Мягкий предел намеренно ничего не
останавливает — отказывает жёсткий, — поэтому это единственное место, где его
пересечение видно.

Ответ по потреблению также содержит стоимость провайдера и клиента, маржу,
списание из включённой квоты/предоплаты/перерасхода, прогноз на 30 дней,
стоимость по исходам, число событий/единиц ресурсов и счётчики сверки резервов.
Поле unpricedCalls сохраняет прежнее значение — только вызовы LLM/эмбеддингов;
unpricedEvents считает все события единого реестра без цены. Счётчики ресурсов
в строке стоимости относятся к оценённым событиям в этой валюте.
resourceTotals группирует всё потребление ресурсов, с ценой и без неё, по
eventKind и unit, указывая число events и целое значение quantity.
reconciliation всегда относится ко всей установке, даже если строки
потребления отфильтрованы; это явно указано полем
reconciliationScope: "global". Блок считает резервы LLM и физических
ресурсов. Счётчик unknown
означает уже отправленную работу с неоднозначным исходом: резерв сохраняется до
авторитетного завершения, а UI показывает её отдельно от ещё не отправленных
резервов. Исправная запись в очереди доставки не считается расхождением;
необрабатываемая или отсутствующая запись увеличивает missingUsageEvent.
Сверка намеренно доступна только администратору через UI/REST и не добавлена в
MCP, SDK или CLI: авторитетное решение о платном эффекте должно оставаться
явным действием оператора-человека.
В CSV столбец resource содержит SKU инструмента или runner-задачи, а model
сохранён для обратной совместимости. Цены и события потребления
неизменяемы; политика бюджета редактируется, но spentMicros и
reservedMicros изменяет только сервер.

GET /llm-prices сохраняет цены LLM в prices, а цены физических ресурсов
возвращает в добавочном массиве resourcePrices. Фильтры:
eventKind=tool_call|runner_seconds|storage_byte_seconds|egress_bytes,
provider, resource и unit. Для
нового тарифа ресурса передайте eventKind, provider, resource,
единицу calls, seconds, byte_seconds или bytes, currency, effectiveFrom,
providerMicrosPerUnit и customerMicrosPerUnit. Суммы — целые
микроединицы валюты за объявленную единицу.

curl -X POST "$MOCKARTY_URL/api/v1/admin/llm-prices" \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"eventKind":"tool_call","provider":"mockarty-agent","resource":"run_api_test","unit":"calls","currency":"USD","effectiveFrom":"2026-08-01T00:00:00Z","providerMicrosPerUnit":250000,"customerMicrosPerUnit":500000}'

Go SDK

prices, err := client.Economics().ListResourcePrices(ctx, mockarty.ResourcePriceQuery{
	EventKind: "tool_call", Provider: "mockarty-agent", Resource: "run_api_test", Unit: "calls",
})

Python SDK

prices = client.economics.list_resource_prices(
    event_kind="tool_call", provider="mockarty-agent", resource="run_api_test", unit="calls"
)

Java SDK

ResourcePriceList prices = client.economics().listResourcePrices(
        "tool_call", "mockarty-agent", "run_api_test", "calls", 100);

# CLI: потребление, новая цена и месячный жёсткий бюджет
mockarty economics usage --group-by mission --days 30
mockarty economics statement --namespace sandbox --output statement.csv
mockarty economics refund --event-id 11111111-1111-1111-1111-111111111111 \
  --reason "провайдер вернул некорректный ответ"
mockarty economics prices append --provider openai --model gpt-4o-mini \
  --currency USD --effective-from 2026-08-01T00:00:00Z --input 0.15 --output 0.60
mockarty economics prices append --kind tool_call --provider mockarty-agent \
  --resource run_api_test --unit calls --currency USD \
  --effective-from 2026-08-01T00:00:00Z --provider-cost 0.25 --customer-price 0.50
mockarty economics budgets set --namespace sandbox --scope workspace \
  --period-start 2026-08-01T00:00:00Z --period-end 2026-09-01T00:00:00Z \
  --hard 100 --require-price

В Go, Python и Java SDK те же операции находятся в группе
Economics / economics. Для тарифов ресурсов используйте
ListResourcePrices / list_resource_prices и
AppendResourcePrice / append_resource_price; прежние ListPrices и
AppendPrice остаются специфичными для LLM.

Настройки электронной почты

Управление лицензиями

Провайдеры идентификации

Управление резервными копиями

Мониторинг базы данных

Вебхуки

Аудит и задачи

Телеметрия

MCP Marketplace (Админ)

Интеграционные токены

Учётные данные интеграции действуют 90 дней с момента создания или ротации.
Ответы создания и ротации возвращают одноразовый token вместе с
credentialExpiresAt; до этой даты выполните ротацию и замените секрет
компонента.

14. Утилиты

Конвертеры (без аутентификации)

Генерация моков из спецификаций

Обратное направление — спецификация из уже имеющихся моков:

curl -X POST "$BASE/generators/spec" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"format":"openapi","namespace":"sandbox","tags":["billing"],"title":"Billing mocks","version":"1.0.0"}'

format — openapi (HTTP-моки → OpenAPI 3.0) или asyncapi (Kafka/RabbitMQ/NATS-моки → AsyncAPI 2.6). Необязательные фильтры сужают набор: folderId, tags (мок должен нести все перечисленные), mockIds; title, version и serverUrl заполняют info и servers документа. В ответе — документ как JSON-значение в spec, массив warnings (mockId, route, reason по каждому моку, который не удалось выразить) и stats (considered, exported). Нужен доступ на чтение к пространству имён; каждая выгрузка пишется в аудит-лог.

Канал AsyncAPI, который нельзя описать одним адресом, несёт и то, чем он является: x-mockarty-protocol (kafka, rabbitmq, nats), x-mockarty-address (topic, queue, routingKey, subject), а для RabbitMQ — x-mockarty-exchange и x-mockarty-routing-key, потому что имя очереди не говорит, какой обменник и какой ключ маршрутизации выбирают этот мок. Если отправить такой документ обратно в /api/v1/generators/asyncapi, мок восстанавливается таким, каким был выгружен. Канал с протоколом, который генератор не умеет выразить (например socket или smtp), пропускается с предупреждением и названием протокола — вместо того чтобы стать Kafka-моком, отвечающим на трафик, для которого его не выгружали.

AI-функции

Уведомления

Задачи агента

Уточнение внешнего действия

Если агент отправил неидемпотентное внешнее действие, но потерял ответ, Mockarty
приостанавливает автоматическое восстановление и показывает Требует проверки
в деталях задачи. Сначала проверьте реальную целевую систему, затем выберите один
результат:

• already_applied — внешняя система подтверждает, что действие выполнено;
• mark_failed — внешняя система подтверждает, что действие не выполнено, и
  задача должна остаться терминальной;
• retry_once — внешняя система подтверждает отсутствие эффекта, поэтому
  Mockarty может выполнить ровно одну новую физическую попытку.

Возьмите receiptKey, version и toolName из
GET /api/v1/agent/tasks/:id. В этом же ответе есть
canReconcileToolReceipts, toolReceiptRetryAllowed и, при блокировке,
toolReceiptReconcileBlockedReason. Владелец задачи видит все квитанции, но для
записи решения именно его учётной записи нужно право Coder → Deploy в
namespace. Решения становятся доступны после остановки задачи. Для отменённой
задачи можно записать already_applied или mark_failed, но нельзя запустить
retry_once. UI объясняет эти состояния вместо неработающей кнопки. Для
повторов одного решения используйте тот же
idempotencyKey. Ответ 409 означает, что receipt изменился: перечитайте его и
проверьте новое состояние. В reason и result добавляйте только безопасное
резюме или внешнюю ссылку — без учётных данных и персональных данных.
Ограничение reason — 2000 байт в UTF-8, а result — 65536 байт в UTF-8
(не количество Unicode-символов); это важно для кириллицы, эмодзи и другого
многобайтового текста. Перед
сохранением Mockarty маскирует распространённые форматы учётных данных как
последний защитный слой, но это не заменяет аккуратный ввод.

cURL

curl -X POST -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: review-42" \
  -d '{"expectedVersion":7,"decision":"already_applied","reason":"Проверено в биллинге","result":"Счёт 42 существует"}' \
  "$MOCKARTY_URL/api/v1/agent/tasks/<task-id>/tool-receipts/<receipt-key>/reconcile"

SDK и CLI

receipt, err := client.AgentTasks().ReconcileToolReceipt(ctx, taskID, receiptKey,
    mockarty.ToolReceiptReconcileRequest{
        ExpectedVersion: 7, IdempotencyKey: "review-42",
        Decision: "already_applied", Reason: "Проверено в биллинге",
        Result: "Счёт 42 существует",
    })

receipt = client.agent_tasks.reconcile_tool_receipt(
    task_id, receipt_key, expected_version=7, idempotency_key="review-42",
    decision="already_applied", reason="Проверено в биллинге",
    result="Счёт 42 существует",
)

ToolReceipt receipt = client.agentTasks().reconcileToolReceipt(
    taskId, receiptKey, 7, "review-42", "already_applied",
    "Проверено в биллинге", "Счёт 42 существует");

mockarty-cli agent receipts list <task-id>
mockarty-cli agent receipts reconcile <task-id> <receipt-key> \
  --expected-version 7 --idempotency-key review-42 \
  --decision already_applied --reason "Проверено в биллинге" \
  --result "Счёт 42 существует"

Восстановление истории чата без workspace

После обновления установки, которая сохраняла чат агента до появления
workspace-изоляции, Mockarty не подключает такую историю к активному чату,
пока владелец явно не выберет workspace. Восстановление доступно на
подключённом admin node (не в Desktop-режиме):

Список никогда не возвращает текст сообщений. Экспорт не назначает workspace.
Для claim обязательно acknowledgeUnknownOrigin: true: у старой истории нет
достоверного исходного workspace. Один и тот же claim можно безопасно повторить;
другой workspace уже не сможет забрать эту историю.

cURL

curl -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/agent/sessions/legacy?limit=50"

curl -X POST -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"payments","acknowledgeUnknownOrigin":true}' \
  "$MOCKARTY_URL/api/v1/agent/sessions/legacy/<session-id>/claim"

Go SDK

page, err := client.AgentTasks().ListLegacySessions(ctx, 50, "")
session, err := client.AgentTasks().ClaimLegacySession(ctx, page.Sessions[0].OriginalID,
    mockarty.LegacyAgentSessionClaimRequest{
        Namespace: "payments", AcknowledgeUnknownOrigin: true,
    })

Python SDK

page = client.agent_tasks.list_legacy_sessions(limit=50)
session = client.agent_tasks.claim_legacy_session(
    page["sessions"][0]["originalId"],
    namespace="payments",
    acknowledge_unknown_origin=True,
)

Java SDK

Map<String, Object> page = client.agentTasks().listLegacySessions(50, null);
Map<String, Object> session = client.agentTasks().claimLegacySession(
    legacySessionId, "payments", null, true);

CLI не выводит содержимое экспорта в терминал, чтобы история случайно не
попала в scrollback:

mockarty-cli agent sessions legacy list
mockarty-cli agent sessions legacy export <session-id> --file ./session.json
mockarty-cli --namespace payments agent sessions legacy claim <session-id> \
  --acknowledge-unknown-origin

Здоровье и мониторинг

Пример ответа health:

{
  "status": "up",
  "releaseId": "1.2.3",
  "checks": {
    "database": {"status": "up"},
    "cache": {"status": "up"}
  }
}

Дашборды

Легаси-эндпоинты статистики (mock-stats, comprehensive-stats,
testing-stats, contracts-stats) удалены вместе с переходом на
пользовательские дашборды — эти метрики теперь отдаются как источники
данных виджетов. См. Пользовательские дашборды.

MCP-сервер

Mockarty предоставляет MCP (Model Context Protocol) сервер по адресу GET /mcp/sse. Подключайте AI-инструменты (Claude Desktop, Cursor) для управления моками через естественный язык.

SSE-события

15. Вызов HTTP-мока

Отправьте запрос на /stubs/<namespace>/<путь-мока> по адресу вашей установки Mockarty. Используйте метод, заголовки, query-параметры и тело, которые ожидает мок. Этот адрес вызывает приложение или тест; административный API-токен, которым вы создавали мок, в адрес стаба не добавляется.

Если вы сгенерировали сервер gRPC, Kafka или другого протокола, направьте клиент на него. Запуск описан в руководстве по генератору серверов.

Выбор пространства

Укажите пространство первым сегментом после /stubs/, чтобы запрос попал к нужным мокам.

# Вызов GET-мока в пространстве sandbox
curl http://localhost:5770/stubs/sandbox/api/users/123

# Вызов POST-мока с JSON-телом
curl -X POST http://localhost:5770/stubs/sandbox/api/orders \
  -H "Content-Type: application/json" \
  -d '{"customerId": "cust-1", "items": [{"id": "item-1", "price": 29.99}]}'

Префиксы шаблонов в ответах

При построении ответов моков Mockarty поддерживает специальные префиксы для подстановки динамических данных:

Пример с параметрами пути:

cURL

# Создание мока с извлечением параметров пути (пространство "sandbox" по умолчанию)
curl -X POST http://localhost:5770/api/v1/mocks \
  -H "Content-Type: application/json" \
  -d '{
    "id": "get-user-by-id",
    "namespace": "sandbox",
    "http": {
      "route": "/api/users/:id",
      "httpMethod": "GET"
    },
    "response": {
      "statusCode": 200,
      "payload": {
        "userId": "$.pathParam.id",
        "name": "$.fake.FirstName",
        "namespace": "$.namespace"
      }
    }
  }'

# Вызываем
curl http://localhost:5770/stubs/sandbox/api/users/42
# Возвращает: {"userId": "42", "name": "Alice", "namespace": "sandbox"}

CLI

echo '{"id":"get-user-by-id","http":{"route":"/api/users/:id","httpMethod":"GET"},"response":{"statusCode":200,"payload":{"userId": "$.pathParam.id", "name": "$.fake.FirstName", "namespace": "$.namespace"}}}' | mockarty-cli mock create -f -

# Вызываем
curl http://localhost:5770/stubs/sandbox/api/users/42

Go

mock := mockarty.NewMockBuilder().
    ID("get-user-by-id").
    HTTP(func(h *mockarty.HTTPBuilder) {
        h.Route("/api/users/:id").Method("GET")
    }).
    Response(func(r *mockarty.ResponseBuilder) {
        r.Status(200).JSONBody(map[string]any{
            "userId":    "$.pathParam.id",
            "name":      "$.fake.FirstName",
            "namespace": "$.namespace",
        })
    }).
    Build()

_, err := client.Mocks().Create(context.Background(), mock)

Python

mock = (
    MockBuilder.http("/api/users/:id", "GET")
    .id("get-user-by-id")
    .respond(200, body={
        "userId": "$.pathParam.id",
        "name": "$.fake.FirstName",
        "namespace": "$.namespace",
    })
    .build()
)

client.mocks.create(mock)

Java

Mock mock = MockBuilder.http("/api/users/:id", "GET")
    .id("get-user-by-id")
    .respond(200, Map.of(
        "userId", "$.pathParam.id",
        "name", "$.fake.FirstName",
        "namespace", "$.namespace"
    ))
    .build();

client.mocks().create(mock);

Настройки автономных миссий пространства

GET /api/v1/missions/{id} возвращает карточку миссии и добавочный объект economics из неизменяемого журнала учёта именно этой миссии. В нём есть вызовы, токены и кэш модели, resources[], unpricedEvents и costs[] по каждой валюте. Перед использованием чисел проверяйте economics.available: false означает, что учёт прочитать не удалось, а не измеренный нулевой расход. Тот же ответ содержит executionBindingsAvailable и executionBindings[] — точные публичные доказательства дочерних выполнений, используемые при отмене. Недоступный список нельзя считать авторитетным пустым списком. MCP-клиенты получают тот же контракт через mission_get.

Для двух retention-полей отсутствие ключа сохраняет текущий override пространства, явный null очищает его и включает наследование политики установки, а целое число от 1 до 3650 задаёт срок. Старые поля автономности, бюджета и источников знаний сохраняют семантику полной замены. GET возвращает ETag, PUT принимает If-Match для оптимистической конкуренции и Idempotency-Key для безопасного точного повтора (412 для устаревшей версии, 409 для конфликта ключа). Предпочитайте CLI или SDK: они читают и сохраняют текущие настройки, передают обе защиты и дают явную операцию наследования. Примеры CLI, Go, Python и Java приведены в разделе Автономные миссии: автоматизация безопасности и хранения пространства.

Для интерактивного запуска получите эффективные настройки непосредственно перед подтверждением и передайте их settingsDigest как expectedSettingsDigest в POST /api/v1/missions. Если человек задал окно уровня миссии, передайте его и в параметре runWindowMinutes предпросмотра, и тем же значением в data.settings.run_window_minutes тела запуска. Тогда digest охватывает точные значения, замораживаемые при старте, и их источники, включая это переопределение. Mockarty сравнивает digest в той же операции до сохранения миссии; несовпадение возвращает 409 и не создаёт миссию.

Если запускающий клиент уже разрешил цель или артефакт, он может записать эту идентичность приёма в targets[] или artifacts[]. Каждый элемент содержит kind, id, положительную revision и канонический digest sha256:<64 строчных шестнадцатеричных символа>. Чтение миссии возвращает запечатанные записи в pins[]. Эти поля сохраняют то, что наблюдал запускающий клиент; они не заменяют проверку конкретного провайдера непосредственно перед внешним эффектом.

Go

request.Targets = []mockarty.MissionRevisionReference{{
    Kind: "repo", ID: "gitlab/mockarty", Revision: 41, Digest: commitDigest,
}}

Python

request.targets = [MissionRevisionReference(
    kind="repo", id="gitlab/mockarty", revision=41, digest=commit_digest,
)]

Java

request.targets(List.of(new MissionRevisionReference()
        .kind("repo").id("gitlab/mockarty").revision(41).digest(commitDigest)));

Проверка знаний агентов

Наблюдения агентов остаются кандидатами, пока уполномоченный рецензент не опубликует их. Откройте Миссии → Знания, чтобы перед решением проверить точное содержимое и метаданные, digest содержимого, источник, происхождение, уверенность, доказательство из миссии, связи и историю. Фильтр состояния позволяет вернуться к опубликованным, заменённым, истёкшим и отклонённым записям. По умолчанию отклонённые кандидаты хранятся 90 дней и никогда не попадают в контекст следующих миссий; кандидаты без решения истекают через 30 дней.

Передавайте версию из list или show и повторно используйте один ключ идемпотентности при ретрае того же решения. 409 Conflict означает, что кандидат уже изменён другим рецензентом: перечитайте его перед новым решением. supersedesId, contradictsIds и expiresAt применимы только к publish.

cURL

curl -H "X-API-Key: $MOCKARTY_API_KEY" \
  'http://127.0.0.1:5770/api/v1/autotester/context/knowledge/review?state=candidate&limit=50'

curl -X POST -H "X-API-Key: $MOCKARTY_API_KEY" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: review-k-42-v1' \
  http://127.0.0.1:5770/api/v1/autotester/context/knowledge/review/k-42 \
  -d '{"decision":"publish","expectedVersion":1,"reason":"Подтверждено связанным запуском"}'

CLI

mockarty-cli agent knowledge review list --state candidate --limit 50
mockarty-cli agent knowledge review list --state published --limit 50
mockarty-cli agent knowledge review show k-42
mockarty-cli agent knowledge review decide k-42 --decision publish \
  --expected-version 1 --reason "Подтверждено связанным запуском" \
  --idempotency-key review-k-42-v1

Go

page, err := client.Experience().ListReview(ctx, mockarty.ExperienceReviewListRequest{Limit: 50})
if err != nil { return err }
for _, candidate := range page.Items { fmt.Println(candidate.ID, candidate.Source) }

_, err = client.Experience().Review(ctx, "k-42", mockarty.ExperienceReviewRequest{
    Decision: "publish", ExpectedVersion: 1,
    Reason: "Подтверждено связанным запуском", IdempotencyKey: "review-k-42-v1",
})

Python

page = client.experience.list_review(limit=50)
for candidate in page.items:
    print(candidate.id, candidate.source)

client.experience.review(
    "k-42", decision="publish", expected_version=1,
    reason="Подтверждено связанным запуском", idempotency_key="review-k-42-v1",
)

Java

client.experience().listReview("published", 50, null).getItems()
    .forEach(item -> System.out.println(item.getId() + " " + item.getSource()));

client.experience().review("k-42", new ExperienceReviewRequest()
    .decision("publish").expectedVersion(1)
    .reason("Подтверждено связанным запуском").idempotencyKey("review-k-42-v1"));

Окружения delivery policy (администратор)

API окружений хранит неизменяемые ревизии политики. Он доступен только
администраторам и только когда Mockarty проверил отдельное authority-подключение
delivery policy. В строгом режиме runtime-узел не использует serving credential
как запасной путь для этих записей.

Ответы содержат метаданные и дайджесты политики, но никогда не содержат bearer
одобрения или seal. После 412 delivery_policy_precondition_failed перечитайте
окружение и повторяйте операцию только после проверки новой ревизии.

Проекция одобрения показывает точного исполнителя, проект, окружение, артефакт,
план, политику, операции и цели. Также она показывает срок, ссылки на аудит и
доказательство, неизменяемые лимиты одной операции и оставшиеся долговечные
совокупные лимиты окружения. usageObserved=false означает, что журнал допуска
ещё не создавался; это не утверждение о нулевом остатке.

Go

env, err := client.DeliveryPolicy().Create(ctx, mockarty.DeliveryPolicyEnvironmentRequest{
    ID: "staging", ProjectID: "payments", Class: "staging", Profile: "standard",
    AuditID: "change-123", EvidenceID: "review-123",
}, "payments-staging-v1")

Python

env = client.delivery_policy.create({
    "id": "staging", "projectId": "payments", "class": "staging",
    "profile": "standard", "auditId": "change-123", "evidenceId": "review-123",
}, idempotency_key="payments-staging-v1")

Java

Map<String, Object> env = client.deliveryPolicy().create(Map.of(
    "id", "staging", "projectId", "payments", "class", "staging",
    "profile", "standard", "auditId", "change-123", "evidenceId", "review-123"
), "payments-staging-v1");

Связанная документация

• Быстрый старт — запуск за 5 минут
• Справочник Faker-функций — генераторы динамических данных
• Руководство по JsonPath — извлечение и трансформация данных
• Система хранилищ — паттерны Global, Chain и Mock Store
• Нагрузочное тестирование — руководство по нагрузочному тестированию
• Фаззинг — руководство по фаззингу безопасности
• Рекордер — запись HTTP-трафика
• Руководство по Web UI — визуальный интерфейс
• Генератор серверов — генерация автономных серверов протоколов
• Вебхуки и колбэки — уведомления о событиях
• Docker и деплой — руководство по production-деплою