API Reference

Complete REST API reference for Mockarty. Base URL: http://localhost:5770 (default).

All request/response bodies use Content-Type: application/json unless noted otherwise.

About URLs in examples: All examples use localhost:5770 as the default address. If your Mockarty instance is deployed on a remote server (e.g. https://mockarty.company.com or http://192.168.1.50:5770), replace localhost:5770 with the actual address. SDKs accept the base URL in the client constructor, so you only set it once. See the Quick Start Guide for a full table of deployment scenarios.

Tip: All examples below are available in multiple languages. Use the tabs to switch between cURL, CLI, and SDK clients. For SDK installation and detailed usage, see the SDK Guide. For CLI tool documentation, see the CLI User Guide.

Hello World: Your First Mock in 30 Seconds

Create a mock and call it – two commands, no configuration needed:

cURL

# 1. Create a mock
curl -X POST http://localhost:5770/api/v1/mocks \
  -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.DateTimeISO"
      }
    }
  }'

# 2. Call the mock (namespace is part of the URL)
curl http://localhost:5770/stubs/sandbox/api/greeting
# Returns: {"message": "Hello, World!", "timestamp": "2026-03-22T10:30:00Z"}

CLI

# Install: https://github.com/mockarty/releases

# 1. Create a mock (namespace defaults to "sandbox")
mockarty-cli mock create \
  --id hello-world \
  --route /api/greeting \
  --method GET \
  --status 200 \
  --body '{"message": "Hello, World!", "timestamp": "$.fake.DateTimeISO"}'

# 2. Call the mock — namespace is always part of the 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() {
	// Namespace defaults to "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.DateTimeISO",
			})
		}).
		Build()

	resp, err := client.Mocks().Create(context.Background(), mock)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Created: %s (overwritten: %v)\n", resp.Mock.ID, resp.Overwritten)
}

Python

# pip install mockarty

from mockarty import MockartyClient
from mockarty.builders import MockBuilder

# Namespace defaults to "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.DateTimeISO",
    })
    .build()
)

result = client.mocks.create(mock)
print(f"Created: {result.mock.id}, overwritten: {result.overwritten}")

Java

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

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

// Namespace defaults to "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.DateTimeISO"
        ))
        .build();

    SaveMockResponse resp = client.mocks().create(mock);
    System.out.println("Created: " + resp.getMock().getId());
}

Kotlin

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

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

// Namespace defaults to "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.DateTimeISO"
        )
    }
}

How it works: You define a mock via POST /api/v1/mocks, then Mockarty serves it at /stubs/<namespace>/<your-route>. The /stubs prefix tells Mockarty to resolve a mock instead of calling its management API. Dynamic values like $.fake.DateTimeISO are replaced at response time.

Table of Contents

1. Authentication
2. Mock Management API (Public)
3. Namespace API
4. Store API
5. Template API
6. CI/CD Integration Guide
7. API Tester API
8. Performance Testing API
9. Fuzzing API
10. Recorder API
11. Contract Testing API
12. Chaos Engineering API
13. Admin API
14. Utility Endpoints
15. Protocol Proxy Endpoints

1. Authentication

Mockarty uses two authentication mechanisms: API tokens for programmatic access and session cookies for the Web UI.

API Tokens

Create tokens in the Web UI (Settings > API Tokens) or via POST /api/v1/auth/tokens.

Include the token in requests using either header:

cURL

# X-API-Key header (namespace "sandbox" is the default)
curl -H "X-API-Key: mk_YOUR_TOKEN" http://localhost:5770/api/v1/mocks

# Authorization: Bearer header
curl -H "Authorization: Bearer mk_YOUR_TOKEN" http://localhost:5770/api/v1/mocks

CLI

# Configure token globally (saved to ~/.mockarty-cli/config.yaml)
mockarty-cli config set token mk_YOUR_TOKEN
mockarty-cli config set namespace sandbox

# Or pass per-command
mockarty-cli mock list --token mk_YOUR_TOKEN

Go

// Token is set via WithAPIKey option; namespace defaults to "sandbox"
client := mockarty.NewClient("http://localhost:5770",
    mockarty.WithAPIKey("mk_YOUR_TOKEN"),
    mockarty.WithNamespace("sandbox"), // optional, "sandbox" is the default
)

Python

# Token is set via api_key parameter; namespace defaults to "sandbox"
client = MockartyClient(
    base_url="http://localhost:5770",
    api_key="mk_YOUR_TOKEN",
    namespace="sandbox",  # optional, "sandbox" is the default
)

Java

// Token is set via apiKey; namespace defaults to "sandbox"
MockartyClient client = MockartyClient.builder()
    .baseUrl("http://localhost:5770")
    .apiKey("mk_YOUR_TOKEN")
    .namespace("sandbox")  // optional, "sandbox" is the default
    .build();

Kotlin

// Token is set via apiKey; namespace defaults to "sandbox"
val client = MockartyClient.builder()
    .baseUrl("http://localhost:5770")
    .apiKey("mk_YOUR_TOKEN")
    .namespace("sandbox")  // optional, "sandbox" is the default
    .build()

Session Authentication

For Web UI and browser-based access:

# Login (returns session cookie)
curl -c cookies.txt -X POST http://localhost:5770/api/v1/auth/login \
  -d '{"username": "admin", "password": "secret"}'

# Use session cookie
curl -b cookies.txt http://localhost:5770/api/v1/mocks

Auth Endpoints

Rate Limiting

API requests are rate-limited based on your license tier. Token-based rate limiting applies per API key.

2. Mock Management API (Public)

These endpoints manage mock definitions. Available at the server root (port 5770). Require authentication with read or write permission.

Create/Update Mock

POST /api/v1/mocks | Auth: user (write)

Creates a new mock or overwrites an existing one (matched by 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

# Namespace defaults to "sandbox"
mockarty-cli mock create \
  --id get-user \
  --route /api/users/list \
  --method GET \
  --status 200 \
  --body '{"id": "$.fake.UUID", "name": "$.fake.FirstName", "email": "$.fake.Email"}'

Go

mock := mockarty.NewMockBuilder().
    ID("get-user").
    Namespace("sandbox"). // optional, "sandbox" is the default
    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")  # optional, "sandbox" is the default
    .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")  // optional, "sandbox" is the default
    .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"  // optional, "sandbox" is the default
    http {
        route = "/api/users/list"
        method = "GET"
    }
    respond {
        statusCode = 200
        body = mapOf(
            "id" to "$.fake.UUID",
            "name" to "$.fake.FirstName",
            "email" to "$.fake.Email"
        )
    }
}

Response:

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

Full mock structure (all fields optional except id):

Condition Structure

What are conditions? Conditions let you return different mock responses depending on the incoming request. Without conditions, a mock matches any request to its route. With conditions, Mockarty inspects the request body, headers, or query parameters and only selects the mock if all conditions pass. This is useful when multiple mocks share the same route but should respond differently based on the request content (e.g., return an error when $.body.status equals "invalid").

The conditions array inside http, grpc, and mcp config objects controls when a mock is selected. Each condition is an object with the following fields:

Assert actions:

Note: The legacy alias match is also accepted and behaves identically to matches.

Example with advanced condition fields:

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

Note: decode, sortArray, and valueFromFile are API-only fields – they are not exposed in the web UI constructor.

Get Mock

GET /api/v1/mocks/:id | Auth: user (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")

List Mocks

GET /api/v1/mocks | Auth: user (read)

cURL

# Namespace "sandbox" is the default
curl -H "X-API-Key: mk_YOUR_TOKEN" \
  "http://localhost:5770/api/v1/mocks?namespace=sandbox&limit=10"

CLI

mockarty-cli mock list --namespace sandbox --limit 10

Go

page, err := client.Mocks().List(context.Background(), &mockarty.ListMocksOptions{
    Namespace: "sandbox", // optional, "sandbox" is the default
    Limit:     10,
})
for _, m := range page.Items {
    fmt.Println(m.ID)
}

Python

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

Java

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

Kotlin

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

Delete Mock (soft)

DELETE /api/v1/mocks/:id | Auth: user (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")

Restore Mock

GET /api/v1/mocks/:id | Auth: user (write)

Purge Mock (permanent)

DELETE /api/v1/mocks/:id/purge | Auth: user (delete)

Get Mock Logs

GET /api/v1/mocks/:id/logs | Auth: user (read)

Returns request history for a mock.

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

Chain Mocks

Batch Create

POST /api/v1/mocks/batch | Auth: user (write)

Creates multiple mocks in a single request.

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

# Batch create from a JSON file (namespace defaults to "sandbox")
mockarty-cli mock create --file mocks.json --batch

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 does not have a dedicated batchCreate method;
// use a loop to create each mock individually
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);

Partial Update (Patch)

PATCH /api/v1/mocks/:id | Auth: user (write)

Partially updates a mock (merges provided fields into the existing mock).

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 does not expose a dedicated patch command.
# Export the mock, edit it locally, and re-apply the full definition — the server
# will update the existing mock by id.
mockarty-cli mock get get-user -o json > mock.json
# edit mock.json (e.g. change response.statusCode to 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().patchMock("get-user", Map.of(
    "response", Map.of("statusCode", 201)
));

Mock Version History

Preview Mock Resolution

GET /api/v1/mocks/preview | Auth: user (read)

Preview which mock would be resolved for a given route/method without actually calling the stub endpoint.

Batch Operations (UI API)

Tags

Mock Folders

Organize mocks into folders for easier management.

Undefined Requests

Captured requests that did not match any mock.

3. Namespace API

Copy mocks example:

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"]
  }'

CLI

mockarty-cli namespace copy \
  --from staging --to production \
  --ids 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. Store API

Three store types for stateful mock scenarios. See Store Systems for concepts.

Global Store

Each POST request adds a single key-value pair. Make separate requests to set multiple keys.

cURL

# Set a key-value pair (one per request)
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"}'

# Read store
curl -H "X-API-Key: mk_YOUR_TOKEN" \
  "http://localhost:5770/api/v1/stores/global?namespace=sandbox"

# Delete a key (key in URL path)
curl -X DELETE -H "X-API-Key: mk_YOUR_TOKEN" \
  "http://localhost:5770/api/v1/stores/global/totalUsers?namespace=sandbox"

CLI

# Set a value (namespace defaults to "sandbox")
mockarty-cli store global set totalUsers 100
mockarty-cli store global set serviceName auth

# Read the store
mockarty-cli store global get

# Delete a key
mockarty-cli store global delete totalUsers

Go

// Set values (uses client's default namespace "sandbox")
err := client.Stores().GlobalSet(context.Background(), "totalUsers", 100)
err = client.Stores().GlobalSet(context.Background(), "serviceName", "auth")

// Read the store
store, err := client.Stores().GlobalGet(context.Background())
fmt.Println(store) // map[totalUsers:100 serviceName:auth ...]

// Delete a key
err = client.Stores().GlobalDelete(context.Background(), "totalUsers")

Python

# Set values (uses client's default namespace "sandbox")
client.stores.global_set("totalUsers", 100)
client.stores.global_set("serviceName", "auth")

# Or set multiple at once
client.stores.global_set_many({"totalUsers": 100, "serviceName": "auth"})

# Read the store
store = client.stores.global_get()
print(store)  # {"totalUsers": 100, "serviceName": "auth"}

# Delete keys
client.stores.global_delete("totalUsers")

Java

// Set values (uses client's default namespace "sandbox")
client.stores().globalSet("totalUsers", 100);
client.stores().globalSet("serviceName", "auth");

// Read the store
Map<String, Object> store = client.stores().globalGet();
System.out.println(store);

// Delete a key
client.stores().globalDelete("totalUsers");

Chain Store

5. Template API

Upload payload templates for use in mock responses via payloadTemplatePath.

Temporary File Storage

Temporary file uploads for use in the agent chat interface. Files are automatically deleted after 30 minutes.

Legacy OpenAPI Generation

6. CI/CD Integration Guide

Mockarty provides full API coverage for CI/CD automation. All examples use API token authentication.

6.1 Running API Tests from CI

cURL

TOKEN="mk_YOUR_TOKEN"
BASE="http://localhost:5770/ui/api"

# 1. Create a collection
COLLECTION_ID=$(curl -s -X POST "$BASE/api-tester/collections" \
  -H "X-API-Key: $TOKEN" \
  -d '{"name": "CI Tests", "description": "Automated test suite"}' | jq -r '.id')

# 2. Add a request with test script
curl -X POST "$BASE/api-tester/collections/$COLLECTION_ID/requests" \
  -H "X-API-Key: $TOKEN" \
  -d '{
    "name": "Get Users",
    "method": "GET",
    "url": "http://localhost:5770/stubs/sandbox/api/users",
    "testScript": "mk.test(\"Status is 200\", function() { mk.response.to.have.status(200); });"
  }'

# 3. Execute the collection (runs all requests + test scripts)
RUN_ID=$(curl -s -X POST "$BASE/api-tester/collections/$COLLECTION_ID/execute" \
  -H "X-API-Key: $TOKEN" \
  -d '{}' | jq -r '.runId')

# 4. Poll for results
curl -s "$BASE/api-tester/test-runs/$RUN_ID" \
  -H "X-API-Key: $TOKEN" | jq '.status, .summary'

CLI

# Run an existing collection by name or ID
mockarty-cli run collection "CI Tests" --wait --format json

# Run and export JUnit report for CI
mockarty-cli run collection "CI Tests" --wait --junit-report results.xml

Go

// Create a collection and execute it
col, err := client.Collections().Create(context.Background(), &mockarty.Collection{
    Name:        "CI Tests",
    Description: "Automated test suite",
})

// Execute the collection
run, err := client.Collections().Execute(context.Background(), col.ID)
fmt.Printf("Run ID: %s, Status: %s\n", run.ID, run.Status)

Python

# Create a collection and execute it
col = client.collections.create({
    "name": "CI Tests",
    "description": "Automated test suite",
})

# Execute the collection
run = client.collections.execute(col.id)
print(f"Run ID: {run.id}, Status: {run.status}")

Java

// Create a collection and execute it
Map<String, Object> col = client.collections().create(Map.of(
    "name", "CI Tests",
    "description", "Automated test suite"
));

String collectionId = (String) col.get("id");
Map<String, Object> run = client.collections().execute(collectionId, Map.of());
System.out.println("Run ID: " + run.get("runId"));

6.2 Running Performance Tests from CI

cURL

# 1. Create perf config (linked to a collection)
CONFIG_ID=$(curl -s -X POST "$BASE/perf-configs" \
  -H "X-API-Key: $TOKEN" \
  -d '{
    "name": "Load Test",
    "collectionId": "'$COLLECTION_ID'",
    "vus": 10,
    "duration": "30s"
  }' | jq -r '.id')

# 2. Run performance test with inline script
curl -X POST "$BASE/perf/run" \
  -H "X-API-Key: $TOKEN" \
  -d '{
    "script": "import http from \"k6/http\"; export default function() { http.get(\"http://localhost:5770/stubs/sandbox/api/users\"); }",
    "options": {"vus": 10, "duration": "30s"}
  }'

# 3. Check results
curl -s "$BASE/perf-results" -H "X-API-Key: $TOKEN" | jq '.[0]'

CLI

# Run a performance test from an existing config
mockarty-cli perf run --config "Load Test" --wait

# Run with inline options
mockarty-cli perf run --vus 10 --duration 30s \
  --url http://localhost:5770/stubs/sandbox/api/users

Go

// Run a performance test
result, err := client.Perf().Run(context.Background(), &mockarty.PerfRunRequest{
    Script:  `import http from "k6/http"; export default function() { http.get("http://localhost:5770/stubs/sandbox/api/users"); }`,
    Options: map[string]any{"vus": 10, "duration": "30s"},
})

// List results
results, err := client.Perf().ListResults(context.Background())

Python

# Run a performance test
result = client.perf.run({
    "script": 'import http from "k6/http"; export default function() { http.get("http://localhost:5770/stubs/sandbox/api/users"); }',
    "options": {"vus": 10, "duration": "30s"},
})

# List results
results = client.perf.list_results()

Java

// Run a performance test
Map<String, Object> result = client.perf().run(Map.of(
    "script", "import http from \"k6/http\"; export default function() { http.get(\"http://localhost:5770/stubs/sandbox/api/users\"); }",
    "options", Map.of("vus", 10, "duration", "30s")
));

6.3 Running Fuzzing from CI

cURL

# 1. Create fuzz config
CONFIG_ID=$(curl -s -X POST "$BASE/fuzzing/configs" \
  -H "X-API-Key: $TOKEN" \
  -d '{
    "name": "API Fuzz",
    "method": "POST",
    "url": "http://target:8080/api/users",
    "headers": {"Content-Type": "application/json"},
    "body": "{\"name\": \"test\"}",
    "payloadCategories": ["sql_injection", "xss"]
  }' | jq -r '.id')

# 2. Start fuzz run
RUN_ID=$(curl -s -X POST "$BASE/fuzzing/run" \
  -H "X-API-Key: $TOKEN" \
  -d '{"configId": "'$CONFIG_ID'"}' | jq -r '.id')

# 3. Check findings
curl -s "$BASE/fuzzing/findings?runId=$RUN_ID" \
  -H "X-API-Key: $TOKEN" | jq '.findings'

CLI

# Run fuzzing from CLI
mockarty-cli fuzz run --config "API Fuzz" --wait

# Quick fuzz a URL
mockarty-cli fuzz quick \
  --url http://target:8080/api/users \
  --method POST \
  --categories sql_injection,xss

Go

// Create a fuzz config and run it
config, err := client.Fuzzing().CreateConfig(context.Background(), &mockarty.FuzzingConfig{
    Name:              "API Fuzz",
    Method:            "POST",
    URL:               "http://target:8080/api/users",
    PayloadCategories: []string{"sql_injection", "xss"},
})

run, err := client.Fuzzing().Run(context.Background(), config.ID)

// Check findings
findings, err := client.Fuzzing().ListFindings(context.Background(), run.ID)

Python

# Create a fuzz config and run it
config = client.fuzzing.create_config({
    "name": "API Fuzz",
    "method": "POST",
    "url": "http://target:8080/api/users",
    "payloadCategories": ["sql_injection", "xss"],
})

run = client.fuzzing.run(config.id)

# Check findings
findings = client.fuzzing.list_findings(run_id=run.id)

Java

// Create a fuzz config and run it
FuzzingConfig config = client.fuzzing().createConfig(Map.of(
    "name", "API Fuzz",
    "method", "POST",
    "url", "http://target:8080/api/users",
    "payloadCategories", List.of("sql_injection", "xss")
));

FuzzingRun run = client.fuzzing().run(config.getId());

6.4 Importing OpenAPI/Postman/HAR

cURL

# Import OpenAPI spec to generate mocks (namespace "sandbox" is the default)
curl -X POST "$BASE/generators/openapi" \
  -H "X-API-Key: $TOKEN" \
  -F "file=@openapi.yaml" \
  -F "namespace=sandbox"

# Import Postman collection to API Tester
curl -X POST "$BASE/api-tester/import/postman" \
  -H "X-API-Key: $TOKEN" \
  -F "file=@collection.json"

# Import HAR recording
curl -X POST "$BASE/api-tester/import/har" \
  -H "X-API-Key: $TOKEN" \
  -F "file=@recording.har"

# Import WSDL for SOAP mocks
curl -X POST "$BASE/api-tester/import/wsdl" \
  -H "X-API-Key: $TOKEN" \
  -F "file=@service.wsdl"

CLI

# Import OpenAPI spec (namespace defaults to "sandbox")
mockarty-cli generate openapi --file openapi.yaml --namespace sandbox

# Import Postman collection
mockarty-cli import postman --file collection.json

# Import HAR recording
mockarty-cli import har --file recording.har

Go

// Import OpenAPI spec to generate mocks
result, err := client.Generator().OpenAPIGenerate(context.Background(),
    "openapi.yaml", // file path
    "sandbox",       // namespace
)

// Import Postman collection
importResult, err := client.Imports().Postman(context.Background(), "collection.json")

Python

# Import OpenAPI spec to generate mocks
result = client.generator.openapi_generate(
    file_path="openapi.yaml",
    namespace="sandbox",  # optional, "sandbox" is the default
)

# Import Postman collection
import_result = client.imports.postman(file_path="collection.json")

Java

// Import OpenAPI spec to generate mocks
GeneratorResponse result = client.generator().openapiGenerate(
    "openapi.yaml", "sandbox"
);

// Import Postman collection
ImportResult importResult = client.imports().postman("collection.json");

6.5 Setting Up Mocks Before Tests

cURL

# Create mocks for your test environment (namespace "sandbox" is the default)
curl -X POST http://localhost:5770/api/v1/mocks \
  -H "X-API-Key: $TOKEN" \
  -d '{
    "id": "ci-user-service",
    "namespace": "sandbox",
    "http": {"route": "/api/users/list", "httpMethod": "GET"},
    "response": {
      "statusCode": 200,
      "payload": {"id": "$.fake.UUID", "name": "Test User"}
    }
  }'

# Verify mock is active
curl http://localhost:5770/stubs/sandbox/api/users/list
# Returns: {"id": "a1b2c3d4-...", "name": "Test User"}

# Cleanup after tests
curl -X DELETE -H "X-API-Key: $TOKEN" \
  http://localhost:5770/api/v1/mocks/ci-user-service

CLI

# Create a mock from a JSON file
mockarty-cli mock create --file ci-mocks.json

# Verify mock is active
curl http://localhost:5770/stubs/sandbox/api/users/list

# Cleanup after tests
mockarty-cli mock delete ci-user-service

Go

// Create mock for CI
mock := mockarty.NewMockBuilder().
    ID("ci-user-service").
    Namespace("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": "Test User",
        })
    }).
    Build()

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

// ... run tests ...

// Cleanup
err = client.Mocks().Delete(context.Background(), "ci-user-service")

Python

# Create mock for CI
mock = (
    MockBuilder.http("/api/users/list", "GET")
    .id("ci-user-service")
    .namespace("sandbox")
    .respond(200, body={"id": "$.fake.UUID", "name": "Test User"})
    .build()
)
client.mocks.create(mock)

# ... run tests ...

# Cleanup
client.mocks.delete("ci-user-service")

Java

// Create mock for CI
Mock mock = MockBuilder.http("/api/users/list", "GET")
    .id("ci-user-service")
    .namespace("sandbox")
    .respond(200, Map.of("id", "$.fake.UUID", "name", "Test User"))
    .build();

client.mocks().create(mock);

// ... run tests ...

// Cleanup
client.mocks().delete("ci-user-service");

7. API Tester API

Full-featured API testing platform (like Postman). All endpoints are under /api/v1/ and require authentication.

Collections

Collection Sharing

Requests

Environments

Test Runs

Unified test run modes

Every row returned from /api/v1/api-tester/test-runs includes a mode field
identifying which execution surface produced the run:

Filter examples:

# All fuzz campaigns in the namespace
curl -H "Authorization: Bearer $TOKEN" \
  "$MOCKARTY_URL/api/v1/api-tester/test-runs?mode=fuzz"

# Every run for a specific chaos experiment
curl -H "Authorization: Bearer $TOKEN" \
  "$MOCKARTY_URL/api/v1/api-tester/test-runs?mode=chaos&referenceId=$EXPERIMENT_ID"

# Paginated functional runs
curl -H "Authorization: Bearer $TOKEN" \
  "$MOCKARTY_URL/api/v1/api-tester/test-runs?mode=functional&limit=50&offset=100"

SDK equivalents:

// 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

Scripts and Execution

Standalone Tests

Schedules (Cron-based)

Import/Export

Protocol Helpers

Kafka Admin

RabbitMQ Admin

8. Performance Testing API

Built-in performance testing with k6-compatible scripting. All endpoints under /api/v1/.

Perf Configs

Run/Stop Tests

Results

Schedules

Runner Tasks

9. Fuzzing API

Security fuzzing with built-in payload categories (SQL injection, XSS, etc.). All endpoints under /api/v1/fuzzing/.

Summary and Payloads

Configs

Import

Protocol Discovery

Runs and Results

Findings

Schedules

10. Recorder API

HTTP traffic recorder (proxy-based). All endpoints under /api/v1/recorder/.

Sessions

Start session example:

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("Session started: %s\n", session.ID)

Python

session = client.recorder.create({
    "targetUrl": "https://api.example.com",
    "port": 8888,
    "name": "API Recording",
})
print(f"Session started: {session.id}")

Java

RecorderSession session = client.recorder().start(Map.of(
    "targetUrl", "https://api.example.com",
    "port", 8888,
    "name", "API Recording"
));
System.out.println("Session started: " + session.getId());

Tip: The same operations are available through mockarty-cli recorder ... — see the CLI User Guide for the command reference.

Entries

Modifications (Request/Response rewriting)

Export

AI Analysis

Configuration

WebSocket

11. Contract Testing API

Contract testing validates that your mocks stay in sync with real API specifications. It supports OpenAPI schema validation, consumer-driven contracts (Pact-compatible), API drift detection, and an API registry (internal marketplace). All endpoints under /api/v1/contract/.

Mock Validation

Configs and Scheduled Runs

Results and Trends

Findings (AI Analysis)

Consumer Contracts (Pact)

API Registry (Internal Marketplace)

Subscriptions

12. Chaos Engineering API

Kubernetes-native chaos engineering for fault injection and resilience testing. Create experiments to inject faults (pod kills, network latency, resource stress) into your clusters and observe how services behave. All endpoints under /api/v1/chaos/.

Presets

Experiments

Experiment Queue

Infrastructure Profiles

Chaos Operator

Kubernetes Resources

13. Admin API

Admin-only endpoints require the admin role. Prefix: /api/v1/admin/.

User Management

Namespace Management (Admin)

Cleanup Policies

LLM/AI Settings

Email Configuration

License Management

Identity Providers

Backup Management

Database Monitoring

Webhooks

Audit and Jobs

Telemetry

MCP Marketplace (Admin)

Integration Tokens

14. Utility Endpoints

Converters (no auth required)

Mock Generation from Specs

AI Features

Notifications

Agent Tasks

Health and Monitoring

Health response example:

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

Dashboards

MCP Server Endpoint

Mockarty exposes an MCP (Model Context Protocol) server at GET /mcp/sse. Connect AI tools (Claude Desktop, Cursor) to manage mocks via natural language.

SSE Events

15. Protocol Proxy Endpoints

Internal endpoints used by generated protocol servers to resolve mocks. No auth required.

How /stubs/* Routing Works

The /stubs/* endpoint is the main mock resolution route. It matches any HTTP method and resolves the appropriate mock based on route, method, conditions, and priority. No authentication is required to call stubs – this is by design, since your application under test calls these endpoints directly.

Namespace routing: The namespace is extracted from the URL path — include it as the first segment after /stubs/. You can also pass it as a query parameter instead. When neither is present, Mockarty falls back to sandbox.

# Recommended: namespace explicit in path (unambiguous, always works)
curl http://localhost:5770/stubs/sandbox/api/users/123
curl http://localhost:5770/stubs/staging/api/users/123

# Alternative: namespace in query parameter
curl "http://localhost:5770/stubs/sandbox/api/users/123?namespace=staging"

# POST with body (conditions are matched against the body)
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}]}'

Template Prefixes in Responses

When building mock responses, Mockarty supports special prefixes to inject dynamic data:

Path parameters example:

cURL

# Create a mock with path parameter extraction (namespace "sandbox" is the default)
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"
      }
    }
  }'

# Call it — namespace is always the first path segment after /stubs/
curl http://localhost:5770/stubs/sandbox/api/users/42
# Returns: {"userId": "42", "name": "Alice", "namespace": "sandbox"}

CLI

mockarty-cli mock create \
  --id get-user-by-id \
  --route /api/users/:id \
  --method GET \
  --status 200 \
  --body '{"userId": "$.pathParam.id", "name": "$.fake.FirstName", "namespace": "$.namespace"}'

# Call it
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);

Related Documentation

• Quick Start - Get running in 5 minutes
• Faker Functions Reference - Dynamic data generators
• JsonPath Guide - Data extraction and transformation
• Store Systems - Global, Chain, and Mock store patterns
• Performance Testing - Perf testing guide
• Fuzzing - Security fuzzing guide
• Contract Testing - API contract validation and drift detection
• Chaos Engineering - Kubernetes fault injection and resilience testing
• Recorder - HTTP traffic recording
• Web UI Guide - Visual interface guide
• Server Generator - Generate standalone protocol servers
• Webhooks & Callbacks - Event notifications
• Docker & Deployment - Production deployment